AmigaOS Documentation Wiki - User contributions [en]

AmiWest 2019 DevCon

2019-10-06T23:48:24Z

Paul Sadlik: /* Syllabus */

= Getting Ready =

Be sure to have the AmigaOS 4.1 Final Edition SDK installed and ready to go. See [[AmiWest Setup]] for complete details on how to get ready.

= Syllabus =

We are aiming to cover the following topics:

* ExecSG past/present/future

* The 3rd party "Enhancer" Software pack or the original Amiga OS API?

* The AmigaOS Daily Driver

* A1222 Graphics Driver

* Personal Projects. You are encouraged to bring your own personal projects to the DevCon where we, as a group, may be able to help you out.

The DevCon will also be tailored to the group. If something is not interesting we can skip it and move on to something that is interesting. Class participation and feedback during the DevCon is mandatory - repeat, mandatory.

= Schedule =

We will start at 09:30 each day so please be there for 09:00. We'll have a lunch break around noon. There is no scheduled end time.

== October 23 (Wednesday) ==

* Introducing the ExecSG Team - Steven Solie
* Enhancer Software Core Walkthrough - Steven Solie

== October 24 (Thursday) ==

* Building a graphics driver for the A1222 - Tony Wyatt
* The Amiga Development Manifesto - Steven Solie

== October 25 (Friday) ==

AmiWest Classic Day

AmigaOS Apps Development

2019-05-12T16:16:43Z

Paul Sadlik:

If you are interested in developing applications for AmigaOS please note that the [[DeveloperDoc:Main|Developer Section]] contains documentation that is useful for developing applications, device drivers, games and other programming projects on AmigaOS. The [[Tutorials:Main|Tutorial Section]] contains a couple of hands-on tutorials that are intended to allow beginning developers to get into programming with step-by-step examples. Finally, the [[Autodocs:Main|Autodocs section]] contains the well-known ''autodocs'', function-by-function documentation of libraries and devices in the AmigaOS system.

Additional assistance is available at [http://forum.hyperion-entertainment.com/ Hyperion Entertainment Forums] and [http://www.os4coding.net/ OS4 Coding].

The following is a sampling of software development applications that may assist with development for AmigaOS.

=== Disclaimer ===
The following list of applications, with the exception of the official AmigaOS Software Development Kit, is neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

== adtools GNU Compiler Collection (GCC) ==

The "adtools" project is the Amiga development tools project that hosts a number of tools that can be used for cross-compiling between various platforms and developing applications for AmigaOS and other Amiga-like platforms. The suite is based on the GCC compiler suite.

[https://github.com/sba1/adtools adtools webpage]

== Amiga Image Storage System AISS ==

The Amiga Image Storage System AISS is an environment to store, access and maintain toolbar images. This can also be used in conjunction with AISS Viewer to easily locate and reference resources into development projects.

[http://os4depot.net/index.php?function=showfile&file=graphics/aiss/aiss.lha Amiga Image Storage System AISS OS4Depot webpage]

[http://os4depot.net/index.php?function=showfile&file=graphics/aiss/aissview.lha AISS Viewer OS4Depot webpage]

== AmigaOS Software Development Kit ==

The official AmigaOS Software Development Kit contains everything needed to get started writing native applications for AmigaOS, including the AmigaOS native GCC compiler, support applications, autodocs, includes and headers.

[http://www.hyperion-entertainment.com/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS Software Development Kit download from Hyperion Entertainment]

== AutoDoc Reader ==

This is a great freeware program to view any text file (autodocs, C-header and others) with database and search options. This is very useful to read the autodocs from the Software Development Kit. Developers documentation in autodoc format is often needed in everyday work. Getting familiar with a lot of files and searching tons of text for desired information is not an easy task. That's where the idea of writing a program that could ease using autodocs originated.

Features include:

* Possibility of creating a database of ours autodocs files,
* Fast and easy documents browsing,
* Possibility of independent loading of autodocs not included in a base,
* Search engine for functions, methods and parameters,
* Easy usage with mouse or keyboard.

The program can act as separate viewer or autodoc-viewing module for other software (e.g. DOpus or GED).

[http://aminet.net/package/dev/misc/AutoDocReader_1v65 AutoDoc Reader Aminet webpage]

== Awk ==

Awk, the powerful language to manipulate and process text files, is available for AmigaOS.

[http://os4depot.net/index.php?function=showfile&file=development/language/awk.lha Awk OS4Depot webpage]

== CMake ==

CMake is a cross platform build tool used to easily build complex projects across different platforms with a single build process. It has been ported to
AmigaOS with the intention of making porting of various complex softwares easier for AmigaOS developers.

[http://os4depot.net/index.php?function=showfile&file=development/cross/cmake.lha CMake OS4Depot webpage]

== CodeBench ==

CodeBench is an Integrated Development Environment (IDE).

Designed purely for use on the latest version of AmigaOS, CodeBench is a management system that is modular to allow adaptation to various programming languages.

The tabbed editor allowing multiple files to be open at any one time. Syntax highlighting and all the usual functions are included: Cut, Copy, Paste, Undo, Find, Replace, Indent etc. Blocks of pre-built code can also be inserted as well as handling highlighted blocks. Also supports color " themes" for familiarity.

Utilising a 'project' based system, all files are grouped together by type and are easily accessible from the Project Window. Editing is a simple matter of selecting the required file and it is opened in the built-in editor. Creating the finished article from the project is a one click event from the toolbar.

[http://www.codebench.co.uk/ CodeBench webpage]

== Cubic IDE ==

The central component of Cubic IDE is GoldED, a fully-featured developers editor for selected versions of AmigaOS. Cubic IDE includes the Installation Wizard, an AmigaGuide authoring mode, LISP and Rexx support packages, the HTML editing environment Webworld and various other add-ons. Together, they form a set of tools for all steps of your development process, from writing source codes and installations over documentation to creation of a web site for your final product.

The editor offers all functions you can expect from a modern program.

* Unlimited undo and redo, configurable syntax highlighting, templates, folding, automatic backups, macro recording and extensive rexx support.
* Single document interface and multiple document interface (all texts in one window)
* Advanced layout and block functions.
* Very high speed
* Optional input aids including context-sensitive completion and automatic case correction.
* Plug-In interface
* Support for encryption
* Spellchecking

All aspects of the Cubic IDE interface are configurable: fonts, colors, toolbars, menus, mouse, etc. Tabbed dialogs simplify the configuration. The software can handle an unlimited number of open screens and windows. Background processes like printing are multithreaded and do not block the user interface. The editor recognizes file types and automatically adjusts the editing environment. For example, the menu will show compiler-specific functions after loading a C source code.

Cubic IDE seamlessly integrates with SAS/C, vbcc, gcc and the StormC3 development environment.

* Free C/C++ compiler and software development kit included for your convenience for AmigaOS.
* Revised online version of "The C Book" included for C beginners.
* Configurable references system for includes, source codes and other material helps you with finding information quickly.
* The QuickInfo function constantly shows information related to the word under the cursor (e.g. parameters of OS functions).
* Source level debugger support for StormC3 users (breakpoints are displayed next to the text).
* The editor automatically highlights matching brackets.
* Symbol browser lists all functions, structures, labels etc. defined in your source codes.
* Built-in grep support allows you to search patterns in a list of files.

[https://www.softwareandcircuits.com/division/amiga/products/cubic/index.html Cubic IDE webpage]

== Debug 101 ==

Debug 101 is a source debugger for AmigaOS. It contains many of the features found in other debuggers like GDB as well as a ReAction GUI.

[http://www.os4depot.net/index.php?function=showfile&file=development/debug/db101.lha Debug 101 OS4Depot webpage]

== Emperor ==

Emperor is a very powerful software to write GUI-based programs. There are C/C++- source codes that are generated by Emperor. They can be easily translated by an external C/C++-Compiler. Developer wanted to make parameterizing of the Graphical User Interface (GUI) and its macro-elements as easy as possible. Following standard-GUI-elements are implemented:

* Screens
* Windows
* Reaction gadgets
* Menus
* Popup-menus
* Requests
* ASL-requests
* Locale-catalogs

Following NON-GUI-elements are implemented:

* Functionmacros
* Install-scripts
* ToolTypes
* Includes
* Libraries
* Declare variables
* InterConnection maps between gadgets
* Create list-arrays for gadgets

With Emperor you are generating a complete C/C++-source code, which only must be compiled by an external compiler. Aim of this program is to assure software developer to create their programs (its source code) by Emperor, because the making of software (opening of windows, file- and fontrequests, menus etc.) is often equal and must not longer copied by programmers from other source codes. Emperor decrees about one or more macros for every GUI-element. Like the menus: here you must, for creating the complete Project-menu (open, close, save, print etc.) and its translation, (in Locale-".catalog"-file) only select the corresponding entry in the list. This is also possible with requests e.g. by making a QuitRequest. These are called in the own source code as function "REQUESTNAME();". But the program should also be for Amigans, who never programmed before, and want an easy way in the programming of AmigaOS-GUIs.

[http://os4depot.net/index.php?function=showfile&file=development/guitool/emperor.lha Emperor OS4Depot webpage]

== Free Pascal ==

Free Pascal is a professional Pascal compiler available for AmigaOS that can target many processor architectures.

[https://blog.alb42.de/fpc-amigaos-4/ Free Pascal for AmigaOS webpage]

== Gui4Cli ==

Gui4Cli is a simple interpreted, event-driven language (no need for previous programming knowledge), which allows you to easily construct great-looking, resizable, font-sensitive GadTools GUIs which (among many other things) can be used to form command lines that can be sent to AmigaDOS or an ARexx port of an other program, for execution. It has many other capabilities too, things like directory & database listviews, maths evaluation, graphics, timers, commodities, file notifications, pipes, appicons etc. etc. With it you can control just about any aspect of the Amiga. Think of it as "Visual DOS".

[http://gui4cli.com/ami/gcmain.htm Gui4Cli webpage]

== Hollywood ==

Hollywood is a multimedia-oriented programming language that can be used to create graphical applications very easily. It was designed with the paradigm to make software creation as easy as possible in mind. Thus, Hollywood is suited for beginners and advanced users alike. Hollywood comes with an extensive function library (encompassing over 800 different commands) that simplifies the creation of games, presentations, and applications, to a great extent. Having been in development since 2002 it is a very mature and stable software package today.

One of the highlights of Hollywood is its inbuilt cross-compiler which can be used to deploy software on many different platforms without having to change a single line of the code. The cross-compiler can compile for all platforms from any platform Hollywood is running on. For instance, you can compile macOS application bundles using the Windows version of Hollywood. There is even an optional add-on that can convert Hollywood applets into stand-alone APKs for release on Android! Android development has never been so easy!

Hollywood is a light-weight, but still powerful programming language whose core is just about two megabytes in size and does not require any external components. Hence, it is ideal for creating programs which run right out of the box. In fact, Hollywood programs will run perfectly from an USB flash drive without any prior installation whatsoever.

Platform architectures currently supported include AmigaOS, Android, iOS, MacOS, Windows, Linux and more.

[https://www.hollywood-mal.com/ Hollywood webpage]

== Lua / LOVE / tolua++ ==

Lua is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description.

Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode with a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal
for configuration, scripting, and rapid prototyping.

LOVE is an awesome framework you can use to make 2D games in Lua. It's free, open-source, and works on Windows, Mac OS X, Linux and AmigaOS.

tolua++ is an extension of toLua, a tool to integrate C/C++ code with Lua. tolua++ includes new features oriented to c++, such as class templates.

tolua is a tool that greatly simplifies the integration of C/C++ code with Lua. Based on a "cleaned" header file, tolua automatically generates the binding code to access C/C++ features from Lua. Using Lua-5.0 API and metamethod facilities, the current version automatically maps C/C++ constants, external variables, functions, namespace, classes, and methods to Lua. It also provides facilities to create Lua modules.

[http://os4depot.net/index.php?function=showfile&file=development/language/liblua.lha Lua OS4Depot webpage]

[http://os4depot.net/index.php?function=showfile&file=development/game/love.lha LOVE OS4Depot webpage]

[http://os4depot.net/index.php?function=showfile&file=development/language/tolua.lha toula++ OS4Depot webpage]

== MUIRexx ==

MUIRexx is a program which serves as an interface between ARexx and MagicUserInterface (MUI). MUIRexx does not provide complete access to all of the capabilities of MagicUserInterface (MUI), however, quite a lot of capability is implemented in MUIRexx such as notification, icon buttons, and application objects (objects that react to icons dropped on them), as well as many standard MUI objects. Complete graphical user interfaces as well as full applications can be developed using MUIRexx and ARexx macros. Additionally, it is also possible to dynamically change or add objects after the application has been created.

[http://aminet.net/package/dev/mui/MUIRexx_3_0a.lha MUIRexx Aminet webpage]

== NoWinED ==

NoWinED is a MUI-based TextEditor that can handle more files simultaneously, using different "pages" for each file. The fact that it is impossible to find a MUI TextEditor on Amiga powerful enough to be used instead of Notepad/Editpad and other editors does not have a reason.

Features:

* Handling of multiple files through tabs that can be managed via titleButtons, a list, and/or an useful context menu which you can open if you click with right mouse button on right scroll titlebutton (this one appears when it's necessary)
* Context menus
* Search and replace module
* Search into opened files module
* File Drag & Drop: dragging one or more files on the NoWinED list the files will be opened in new tabs, dragging a file on a page will open it on the current page. Finally dragging more files on a tab will open the first file in the current tab, and the others in new pages (AROS lacks Drag & Drop)
* Basic texteditor features (C&P, select all, Undo, Redo, etc...).
* Usage from keyboard supported
* UTF support (you can load UTF files and export UTF with/without BOM or ASCII)
* CR/LF/CR+LF support (you can load any kind of txt file and export text with LF/CR/CR+LF)
* Wrapping process of your text at the column you want
* Backup of all opened files (you can set time between a backup process and another one)
* AutoSave of current file (you can set time between a autosave process and another one)
* Programmable Fn keys with independent profiles
* Graphic printout

[http://shinkuro.altervista.org/amiga/software/nowined.htm NoWinED webpage]

== PortablE ==

PortablE is a recreation of the AmigaE programming language, along with many improvements, and the aim of being portable across many platforms.

PortablE works by translating your E code into C++, and then using GCC to compile it into an executable that you can run. But you don't need to worry about these details, because the PEGCC program will handle them for you. PortablE needs an installation of GCC, which is free & easily installed.

[http://cshandley.co.uk/portable/ PortableE webpage]

== ProAction ==

A powerful interface between any Arexx enabled scripting language and the AmigaOS ReAction GUI system. ProAction provides GUIs for script writers, using a unique "dual ARexx Port" approach. ProAction itself is an ARexx host which provides functions for building and managing the GUI, then GUI events are sent as commands to an ARexx port managed by the script.

It can be used from any language that can support an ARexx host. (ARexx (with rexxsupport.libray) python via arexx.so etc etc)

[http://www.broad.ology.org.uk/amiga/proaction/index.html ProAction webpage]

== SDK Browser ==

The SDK Browser provides any Amiga Programmer a quick reference tool into the live AmigaOS Software Development Kit installation on your Amiga, via a 100% graphical (GUI) based tool. It can help you find the format (prototype) for any AmigaOS4.x system call as well as lookup a specific structure reference, method, tag item, what-have-you, quicker than any other tool. Or, you can simply use it as a great way to wander through the AmigaOS4.x development documentation (AutoDocs, Includes, etc.) to learn more about how to program for this great machine and its powerful operating system. There is a great deal of (largely untapped) power available with the "standard" OS if you only know where to look.

Features include:

* Fully multitasking search bar with start/stop and pause/resume. File pattern filter added to search bar, and maintained separately for each search type. Interact with results as they are found, or continue to use all other parts of the SDK Browser as the search continues in the background. Search will continue even when hidden or iconified, and is controllable from the commodity exchange as well.
* History Bar. Quickly return to any of the last 20 items that have been viewed previously. Browse forward or back with the arrow buttons, or pull down and select a new position within the browser history. The history bar works like a combination of a web browser forward and back buttons and a rotating 20 item tabbed display. Giving you the flexibility to quickly work with the last 20 items that have been referenced already.
* Support for more than one interface(API) found within the same library. If the XML file for a given library contains more than one interface for accessing that library, then the SDK Browser will create a new browsable Library tree for each interface and name them with their respective interface name. This is also why the Interface name was added to each library entry under the Library list.
* Faster than ever before using newly optimized viewing routines and less disk access.
* Function calls under "Commands" or an open view of any "Library" now displays just the description of the function call within the AutoDoc instead of displaying the entire AutoDoc and attempting to search for the start of the description. This makes for a cleaner an easier to read display, while the entire AutoDoc file is still instantly available by selecting the Library name itself, or browsing the "AutoDocs" directly.
* Quick find ANY item in the active list just by typing the first few letters of its name.
* New "Includes" browsing. Live browse the system includes using the new embedded directory scanner.
* Convenient "Send To" menu for launching a helpful set of external viewers right from the SDK Browser. Quickly open source files into the editor of your choice, or open HTML files directly into your web browser of choice. You can also launch the currently selected file with "MultiView", "AmiPDF", or even "Unarc" those archives.
* Improved interface handles all Library, Commands, AutoDocs, and Includes browsing under the "SDK" clicktab, while also giving the user a "Project" tab and directory scan lister for browsing their own project source or any where you need to, quickly and easily from one tool.
* Extensive keyboard controls to enhance the existing "mouse-over" focused movement keys and "mouse-wheel" support.
* Programmable SDK and search paths.
* Programmable EDITOR and WEBBROWSER tooltypes for use by the "Send To" menu.

[http://bitbybitsoftwaregroup.com/sdkbrowser/index.php SDK Browser webpage]

== vbcc ==

vbcc is a highly optimizing portable and retargetable ISO C compiler available for AmigaOS. It supports ISO C according to ISO/IEC 9899:1989 and a subset of the new standard ISO/IEC 9899:1999 (C99).

[http://sun.hasenbraten.de/vbcc/ vbcc webpage]

== Vim ==

Vim is a highly configurable text editor built to make creating and changing any kind of text very efficient. Vim is rock stable and is continuously being developed to become even better. Among its features are:

* persistent, multi-level undo tree
* extensive plugin system
* support for hundreds of programming languages and file formats
* powerful search and replace
* integrates with many tools

Please note that this is not a straight port of the upstream version. It includes a full MUI GUI with most of the bells and whistles found in Vim on any of the major platforms. "TheBar" custom class must be installed for MUI for this version of Vim.

[https://sourceforge.net/projects/spaden/ AmigaOS Vim webpage]

[https://github.com/amiga-mui/thebar TheBar custom class webpage]

AmigaOS Apps Development

2019-05-12T16:09:41Z

Paul Sadlik: /* AmigaOS Software Development Kit */

If you are interested in developing applications for AmigaOS please note that the [[DeveloperDoc:Main|Developer Section]] contains documentation that is useful for developing applications, device drivers, games and other programming projects on AmigaOS. The [[Tutorials:Main|Tutorial Section]] contains a couple of hands-on tutorials that are intended to allow beginning developers to get into programming with step-by-step examples. Finally, the [[Autodocs:Main|Autodocs section]] contains the well-known ''autodocs'', function-by-function documentation of libraries and devices in the AmigaOS system.

Additional assistance is available at [http://forum.hyperion-entertainment.com/ Hyperion Entertainment Forums] and [http://www.os4coding.net/ OS4 Coding].

The following is a sampling of software development applications that may assist with development for AmigaOS.

=== Disclaimer ===
The following list of applications, with the exception of the official AmigaOS Software Development Kit, is neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

== Amiga Image Storage System AISS ==

The Amiga Image Storage System AISS is an environment to store, access and maintain toolbar images. This can also be used in conjunction with AISS Viewer to easily locate and reference resources into development projects.

[http://os4depot.net/index.php?function=showfile&file=graphics/aiss/aiss.lha Amiga Image Storage System AISS OS4Depot webpage]

[http://os4depot.net/index.php?function=showfile&file=graphics/aiss/aissview.lha AISS Viewer OS4Depot webpage]

== AmigaOS Software Development Kit ==

The official AmigaOS Software Development Kit contains everything needed to get started writing native applications for AmigaOS, including the AmigaOS native GCC compiler, support applications, autodocs, includes and headers.

[http://www.hyperion-entertainment.com/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS Software Development Kit download from Hyperion Entertainment]

== AutoDoc Reader ==

This is a great freeware program to view any text file (autodocs, C-header and others) with database and search options. This is very useful to read the autodocs from the Software Development Kit. Developers documentation in autodoc format is often needed in everyday work. Getting familiar with a lot of files and searching tons of text for desired information is not an easy task. That's where the idea of writing a program that could ease using autodocs originated.

Features include:

* Possibility of creating a database of ours autodocs files,
* Fast and easy documents browsing,
* Possibility of independent loading of autodocs not included in a base,
* Search engine for functions, methods and parameters,
* Easy usage with mouse or keyboard.

The program can act as separate viewer or autodoc-viewing module for other software (e.g. DOpus or GED).

[http://aminet.net/package/dev/misc/AutoDocReader_1v65 AutoDoc Reader Aminet webpage]

== Awk ==

Awk, the powerful language to manipulate and process text files, is available for AmigaOS.

[http://os4depot.net/index.php?function=showfile&file=development/language/awk.lha Awk OS4Depot webpage]

== CMake ==

CMake is a cross platform build tool used to easily build complex projects across different platforms with a single build process. It has been ported to
AmigaOS with the intention of making porting of various complex softwares easier for AmigaOS developers.

[http://os4depot.net/index.php?function=showfile&file=development/cross/cmake.lha CMake OS4Depot webpage]

== CodeBench ==

CodeBench is an Integrated Development Environment (IDE).

Designed purely for use on the latest version of AmigaOS, CodeBench is a management system that is modular to allow adaptation to various programming languages.

The tabbed editor allowing multiple files to be open at any one time. Syntax highlighting and all the usual functions are included: Cut, Copy, Paste, Undo, Find, Replace, Indent etc. Blocks of pre-built code can also be inserted as well as handling highlighted blocks. Also supports color " themes" for familiarity.

Utilising a 'project' based system, all files are grouped together by type and are easily accessible from the Project Window. Editing is a simple matter of selecting the required file and it is opened in the built-in editor. Creating the finished article from the project is a one click event from the toolbar.

[http://www.codebench.co.uk/ CodeBench webpage]

== Cubic IDE ==

The central component of Cubic IDE is GoldED, a fully-featured developers editor for selected versions of AmigaOS. Cubic IDE includes the Installation Wizard, an AmigaGuide authoring mode, LISP and Rexx support packages, the HTML editing environment Webworld and various other add-ons. Together, they form a set of tools for all steps of your development process, from writing source codes and installations over documentation to creation of a web site for your final product.

The editor offers all functions you can expect from a modern program.

* Unlimited undo and redo, configurable syntax highlighting, templates, folding, automatic backups, macro recording and extensive rexx support.
* Single document interface and multiple document interface (all texts in one window)
* Advanced layout and block functions.
* Very high speed
* Optional input aids including context-sensitive completion and automatic case correction.
* Plug-In interface
* Support for encryption
* Spellchecking

All aspects of the Cubic IDE interface are configurable: fonts, colors, toolbars, menus, mouse, etc. Tabbed dialogs simplify the configuration. The software can handle an unlimited number of open screens and windows. Background processes like printing are multithreaded and do not block the user interface. The editor recognizes file types and automatically adjusts the editing environment. For example, the menu will show compiler-specific functions after loading a C source code.

Cubic IDE seamlessly integrates with SAS/C, vbcc, gcc and the StormC3 development environment.

* Free C/C++ compiler and software development kit included for your convenience for AmigaOS.
* Revised online version of "The C Book" included for C beginners.
* Configurable references system for includes, source codes and other material helps you with finding information quickly.
* The QuickInfo function constantly shows information related to the word under the cursor (e.g. parameters of OS functions).
* Source level debugger support for StormC3 users (breakpoints are displayed next to the text).
* The editor automatically highlights matching brackets.
* Symbol browser lists all functions, structures, labels etc. defined in your source codes.
* Built-in grep support allows you to search patterns in a list of files.

[https://www.softwareandcircuits.com/division/amiga/products/cubic/index.html Cubic IDE webpage]

== Debug 101 ==

Debug 101 is a source debugger for AmigaOS. It contains many of the features found in other debuggers like GDB as well as a ReAction GUI.

[http://www.os4depot.net/index.php?function=showfile&file=development/debug/db101.lha Debug 101 OS4Depot webpage]

== Emperor ==

Emperor is a very powerful software to write GUI-based programs. There are C/C++- source codes that are generated by Emperor. They can be easily translated by an external C/C++-Compiler. Developer wanted to make parameterizing of the Graphical User Interface (GUI) and its macro-elements as easy as possible. Following standard-GUI-elements are implemented:

* Screens
* Windows
* Reaction gadgets
* Menus
* Popup-menus
* Requests
* ASL-requests
* Locale-catalogs

Following NON-GUI-elements are implemented:

* Functionmacros
* Install-scripts
* ToolTypes
* Includes
* Libraries
* Declare variables
* InterConnection maps between gadgets
* Create list-arrays for gadgets

With Emperor you are generating a complete C/C++-source code, which only must be compiled by an external compiler. Aim of this program is to assure software developer to create their programs (its source code) by Emperor, because the making of software (opening of windows, file- and fontrequests, menus etc.) is often equal and must not longer copied by programmers from other source codes. Emperor decrees about one or more macros for every GUI-element. Like the menus: here you must, for creating the complete Project-menu (open, close, save, print etc.) and its translation, (in Locale-".catalog"-file) only select the corresponding entry in the list. This is also possible with requests e.g. by making a QuitRequest. These are called in the own source code as function "REQUESTNAME();". But the program should also be for Amigans, who never programmed before, and want an easy way in the programming of AmigaOS-GUIs.

[http://os4depot.net/index.php?function=showfile&file=development/guitool/emperor.lha Emperor OS4Depot webpage]

== Free Pascal ==

Free Pascal is a professional Pascal compiler available for AmigaOS that can target many processor architectures.

[https://blog.alb42.de/fpc-amigaos-4/ Free Pascal for AmigaOS webpage]

== adtools GNU Compiler Collection (GCC) ==

The "adtools" project is the Amiga development tools project that hosts a number of tools that can be used for cross-compiling between various platforms and developing applications for AmigaOS and other Amiga-like platforms. The suite is based on the GCC compiler suite.

[https://github.com/sba1/adtools adtools webpage]

== Gui4Cli ==

Gui4Cli is a simple interpreted, event-driven language (no need for previous programming knowledge), which allows you to easily construct great-looking, resizable, font-sensitive GadTools GUIs which (among many other things) can be used to form command lines that can be sent to AmigaDOS or an ARexx port of an other program, for execution. It has many other capabilities too, things like directory & database listviews, maths evaluation, graphics, timers, commodities, file notifications, pipes, appicons etc. etc. With it you can control just about any aspect of the Amiga. Think of it as "Visual DOS".

[http://gui4cli.com/ami/gcmain.htm Gui4Cli webpage]

== Hollywood ==

Hollywood is a multimedia-oriented programming language that can be used to create graphical applications very easily. It was designed with the paradigm to make software creation as easy as possible in mind. Thus, Hollywood is suited for beginners and advanced users alike. Hollywood comes with an extensive function library (encompassing over 800 different commands) that simplifies the creation of games, presentations, and applications, to a great extent. Having been in development since 2002 it is a very mature and stable software package today.

One of the highlights of Hollywood is its inbuilt cross-compiler which can be used to deploy software on many different platforms without having to change a single line of the code. The cross-compiler can compile for all platforms from any platform Hollywood is running on. For instance, you can compile macOS application bundles using the Windows version of Hollywood. There is even an optional add-on that can convert Hollywood applets into stand-alone APKs for release on Android! Android development has never been so easy!

Hollywood is a light-weight, but still powerful programming language whose core is just about two megabytes in size and does not require any external components. Hence, it is ideal for creating programs which run right out of the box. In fact, Hollywood programs will run perfectly from an USB flash drive without any prior installation whatsoever.

Platform architectures currently supported include AmigaOS, Android, iOS, MacOS, Windows, Linux and more.

[https://www.hollywood-mal.com/ Hollywood webpage]

== Lua / LOVE / tolua++ ==

Lua is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description.

Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode with a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal
for configuration, scripting, and rapid prototyping.

LOVE is an awesome framework you can use to make 2D games in Lua. It's free, open-source, and works on Windows, Mac OS X, Linux and AmigaOS.

tolua++ is an extension of toLua, a tool to integrate C/C++ code with Lua. tolua++ includes new features oriented to c++, such as class templates.

tolua is a tool that greatly simplifies the integration of C/C++ code with Lua. Based on a "cleaned" header file, tolua automatically generates the binding code to access C/C++ features from Lua. Using Lua-5.0 API and metamethod facilities, the current version automatically maps C/C++ constants, external variables, functions, namespace, classes, and methods to Lua. It also provides facilities to create Lua modules.

[http://os4depot.net/index.php?function=showfile&file=development/language/liblua.lha Lua OS4Depot webpage]

[http://os4depot.net/index.php?function=showfile&file=development/game/love.lha LOVE OS4Depot webpage]

[http://os4depot.net/index.php?function=showfile&file=development/language/tolua.lha toula++ OS4Depot webpage]

== MUIRexx ==

MUIRexx is a program which serves as an interface between ARexx and MagicUserInterface (MUI). MUIRexx does not provide complete access to all of the capabilities of MagicUserInterface (MUI), however, quite a lot of capability is implemented in MUIRexx such as notification, icon buttons, and application objects (objects that react to icons dropped on them), as well as many standard MUI objects. Complete graphical user interfaces as well as full applications can be developed using MUIRexx and ARexx macros. Additionally, it is also possible to dynamically change or add objects after the application has been created.

[http://aminet.net/package/dev/mui/MUIRexx_3_0a.lha MUIRexx Aminet webpage]

== NoWinED ==

NoWinED is a MUI-based TextEditor that can handle more files simultaneously, using different "pages" for each file. The fact that it is impossible to find a MUI TextEditor on Amiga powerful enough to be used instead of Notepad/Editpad and other editors does not have a reason.

Features:

* Handling of multiple files through tabs that can be managed via titleButtons, a list, and/or an useful context menu which you can open if you click with right mouse button on right scroll titlebutton (this one appears when it's necessary)
* Context menus
* Search and replace module
* Search into opened files module
* File Drag & Drop: dragging one or more files on the NoWinED list the files will be opened in new tabs, dragging a file on a page will open it on the current page. Finally dragging more files on a tab will open the first file in the current tab, and the others in new pages (AROS lacks Drag & Drop)
* Basic texteditor features (C&P, select all, Undo, Redo, etc...).
* Usage from keyboard supported
* UTF support (you can load UTF files and export UTF with/without BOM or ASCII)
* CR/LF/CR+LF support (you can load any kind of txt file and export text with LF/CR/CR+LF)
* Wrapping process of your text at the column you want
* Backup of all opened files (you can set time between a backup process and another one)
* AutoSave of current file (you can set time between a autosave process and another one)
* Programmable Fn keys with independent profiles
* Graphic printout

[http://shinkuro.altervista.org/amiga/software/nowined.htm NoWinED webpage]

== PortablE ==

PortablE is a recreation of the AmigaE programming language, along with many improvements, and the aim of being portable across many platforms.

PortablE works by translating your E code into C++, and then using GCC to compile it into an executable that you can run. But you don't need to worry about these details, because the PEGCC program will handle them for you. PortablE needs an installation of GCC, which is free & easily installed.

[http://cshandley.co.uk/portable/ PortableE webpage]

== ProAction ==

A powerful interface between any Arexx enabled scripting language and the AmigaOS ReAction GUI system. ProAction provides GUIs for script writers, using a unique "dual ARexx Port" approach. ProAction itself is an ARexx host which provides functions for building and managing the GUI, then GUI events are sent as commands to an ARexx port managed by the script.

It can be used from any language that can support an ARexx host. (ARexx (with rexxsupport.libray) python via arexx.so etc etc)

[http://www.broad.ology.org.uk/amiga/proaction/index.html ProAction webpage]

== SDK Browser ==

The SDK Browser provides any Amiga Programmer a quick reference tool into the live AmigaOS Software Development Kit installation on your Amiga, via a 100% graphical (GUI) based tool. It can help you find the format (prototype) for any AmigaOS4.x system call as well as lookup a specific structure reference, method, tag item, what-have-you, quicker than any other tool. Or, you can simply use it as a great way to wander through the AmigaOS4.x development documentation (AutoDocs, Includes, etc.) to learn more about how to program for this great machine and its powerful operating system. There is a great deal of (largely untapped) power available with the "standard" OS if you only know where to look.

Features include:

* Fully multitasking search bar with start/stop and pause/resume. File pattern filter added to search bar, and maintained separately for each search type. Interact with results as they are found, or continue to use all other parts of the SDK Browser as the search continues in the background. Search will continue even when hidden or iconified, and is controllable from the commodity exchange as well.
* History Bar. Quickly return to any of the last 20 items that have been viewed previously. Browse forward or back with the arrow buttons, or pull down and select a new position within the browser history. The history bar works like a combination of a web browser forward and back buttons and a rotating 20 item tabbed display. Giving you the flexibility to quickly work with the last 20 items that have been referenced already.
* Support for more than one interface(API) found within the same library. If the XML file for a given library contains more than one interface for accessing that library, then the SDK Browser will create a new browsable Library tree for each interface and name them with their respective interface name. This is also why the Interface name was added to each library entry under the Library list.
* Faster than ever before using newly optimized viewing routines and less disk access.
* Function calls under "Commands" or an open view of any "Library" now displays just the description of the function call within the AutoDoc instead of displaying the entire AutoDoc and attempting to search for the start of the description. This makes for a cleaner an easier to read display, while the entire AutoDoc file is still instantly available by selecting the Library name itself, or browsing the "AutoDocs" directly.
* Quick find ANY item in the active list just by typing the first few letters of its name.
* New "Includes" browsing. Live browse the system includes using the new embedded directory scanner.
* Convenient "Send To" menu for launching a helpful set of external viewers right from the SDK Browser. Quickly open source files into the editor of your choice, or open HTML files directly into your web browser of choice. You can also launch the currently selected file with "MultiView", "AmiPDF", or even "Unarc" those archives.
* Improved interface handles all Library, Commands, AutoDocs, and Includes browsing under the "SDK" clicktab, while also giving the user a "Project" tab and directory scan lister for browsing their own project source or any where you need to, quickly and easily from one tool.
* Extensive keyboard controls to enhance the existing "mouse-over" focused movement keys and "mouse-wheel" support.
* Programmable SDK and search paths.
* Programmable EDITOR and WEBBROWSER tooltypes for use by the "Send To" menu.

[http://bitbybitsoftwaregroup.com/sdkbrowser/index.php SDK Browser webpage]

== vbcc ==

vbcc is a highly optimizing portable and retargetable ISO C compiler available for AmigaOS. It supports ISO C according to ISO/IEC 9899:1989 and a subset of the new standard ISO/IEC 9899:1999 (C99).

[http://sun.hasenbraten.de/vbcc/ vbcc webpage]

== Vim ==

Vim is a highly configurable text editor built to make creating and changing any kind of text very efficient. Vim is rock stable and is continuously being developed to become even better. Among its features are:

* persistent, multi-level undo tree
* extensive plugin system
* support for hundreds of programming languages and file formats
* powerful search and replace
* integrates with many tools

Please note that this is not a straight port of the upstream version. It includes a full MUI GUI with most of the bells and whistles found in Vim on any of the major platforms. "TheBar" custom class must be installed for MUI for this version of Vim.

[https://sourceforge.net/projects/spaden/ AmigaOS Vim webpage]

[https://github.com/amiga-mui/thebar TheBar custom class webpage]

AmigaOS Apps Development

2019-05-12T16:08:16Z

Paul Sadlik: /* GNU Compiler Collection GCC */

If you are interested in developing applications for AmigaOS please note that the [[DeveloperDoc:Main|Developer Section]] contains documentation that is useful for developing applications, device drivers, games and other programming projects on AmigaOS. The [[Tutorials:Main|Tutorial Section]] contains a couple of hands-on tutorials that are intended to allow beginning developers to get into programming with step-by-step examples. Finally, the [[Autodocs:Main|Autodocs section]] contains the well-known ''autodocs'', function-by-function documentation of libraries and devices in the AmigaOS system.

Additional assistance is available at [http://forum.hyperion-entertainment.com/ Hyperion Entertainment Forums] and [http://www.os4coding.net/ OS4 Coding].

The following is a sampling of software development applications that may assist with development for AmigaOS.

=== Disclaimer ===
The following list of applications, with the exception of the official AmigaOS Software Development Kit, is neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

== Amiga Image Storage System AISS ==

The Amiga Image Storage System AISS is an environment to store, access and maintain toolbar images. This can also be used in conjunction with AISS Viewer to easily locate and reference resources into development projects.

[http://os4depot.net/index.php?function=showfile&file=graphics/aiss/aiss.lha Amiga Image Storage System AISS OS4Depot webpage]

[http://os4depot.net/index.php?function=showfile&file=graphics/aiss/aissview.lha AISS Viewer OS4Depot webpage]

== AmigaOS Software Development Kit ==

The official AmigaOS Software Development Kit contains everything needed to get started writing native applications for AmigaOS.

[http://www.hyperion-entertainment.com/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS Software Development Kit download from Hyperion Entertainment]

== AutoDoc Reader ==

This is a great freeware program to view any text file (autodocs, C-header and others) with database and search options. This is very useful to read the autodocs from the Software Development Kit. Developers documentation in autodoc format is often needed in everyday work. Getting familiar with a lot of files and searching tons of text for desired information is not an easy task. That's where the idea of writing a program that could ease using autodocs originated.

Features include:

* Possibility of creating a database of ours autodocs files,
* Fast and easy documents browsing,
* Possibility of independent loading of autodocs not included in a base,
* Search engine for functions, methods and parameters,
* Easy usage with mouse or keyboard.

The program can act as separate viewer or autodoc-viewing module for other software (e.g. DOpus or GED).

[http://aminet.net/package/dev/misc/AutoDocReader_1v65 AutoDoc Reader Aminet webpage]

== Awk ==

Awk, the powerful language to manipulate and process text files, is available for AmigaOS.

[http://os4depot.net/index.php?function=showfile&file=development/language/awk.lha Awk OS4Depot webpage]

== CMake ==

CMake is a cross platform build tool used to easily build complex projects across different platforms with a single build process. It has been ported to
AmigaOS with the intention of making porting of various complex softwares easier for AmigaOS developers.

[http://os4depot.net/index.php?function=showfile&file=development/cross/cmake.lha CMake OS4Depot webpage]

== CodeBench ==

CodeBench is an Integrated Development Environment (IDE).

Designed purely for use on the latest version of AmigaOS, CodeBench is a management system that is modular to allow adaptation to various programming languages.

The tabbed editor allowing multiple files to be open at any one time. Syntax highlighting and all the usual functions are included: Cut, Copy, Paste, Undo, Find, Replace, Indent etc. Blocks of pre-built code can also be inserted as well as handling highlighted blocks. Also supports color " themes" for familiarity.

Utilising a 'project' based system, all files are grouped together by type and are easily accessible from the Project Window. Editing is a simple matter of selecting the required file and it is opened in the built-in editor. Creating the finished article from the project is a one click event from the toolbar.

[http://www.codebench.co.uk/ CodeBench webpage]

== Cubic IDE ==

The central component of Cubic IDE is GoldED, a fully-featured developers editor for selected versions of AmigaOS. Cubic IDE includes the Installation Wizard, an AmigaGuide authoring mode, LISP and Rexx support packages, the HTML editing environment Webworld and various other add-ons. Together, they form a set of tools for all steps of your development process, from writing source codes and installations over documentation to creation of a web site for your final product.

The editor offers all functions you can expect from a modern program.

* Unlimited undo and redo, configurable syntax highlighting, templates, folding, automatic backups, macro recording and extensive rexx support.
* Single document interface and multiple document interface (all texts in one window)
* Advanced layout and block functions.
* Very high speed
* Optional input aids including context-sensitive completion and automatic case correction.
* Plug-In interface
* Support for encryption
* Spellchecking

All aspects of the Cubic IDE interface are configurable: fonts, colors, toolbars, menus, mouse, etc. Tabbed dialogs simplify the configuration. The software can handle an unlimited number of open screens and windows. Background processes like printing are multithreaded and do not block the user interface. The editor recognizes file types and automatically adjusts the editing environment. For example, the menu will show compiler-specific functions after loading a C source code.

Cubic IDE seamlessly integrates with SAS/C, vbcc, gcc and the StormC3 development environment.

* Free C/C++ compiler and software development kit included for your convenience for AmigaOS.
* Revised online version of "The C Book" included for C beginners.
* Configurable references system for includes, source codes and other material helps you with finding information quickly.
* The QuickInfo function constantly shows information related to the word under the cursor (e.g. parameters of OS functions).
* Source level debugger support for StormC3 users (breakpoints are displayed next to the text).
* The editor automatically highlights matching brackets.
* Symbol browser lists all functions, structures, labels etc. defined in your source codes.
* Built-in grep support allows you to search patterns in a list of files.

[https://www.softwareandcircuits.com/division/amiga/products/cubic/index.html Cubic IDE webpage]

== Debug 101 ==

Debug 101 is a source debugger for AmigaOS. It contains many of the features found in other debuggers like GDB as well as a ReAction GUI.

[http://www.os4depot.net/index.php?function=showfile&file=development/debug/db101.lha Debug 101 OS4Depot webpage]

== Emperor ==

Emperor is a very powerful software to write GUI-based programs. There are C/C++- source codes that are generated by Emperor. They can be easily translated by an external C/C++-Compiler. Developer wanted to make parameterizing of the Graphical User Interface (GUI) and its macro-elements as easy as possible. Following standard-GUI-elements are implemented:

* Screens
* Windows
* Reaction gadgets
* Menus
* Popup-menus
* Requests
* ASL-requests
* Locale-catalogs

Following NON-GUI-elements are implemented:

* Functionmacros
* Install-scripts
* ToolTypes
* Includes
* Libraries
* Declare variables
* InterConnection maps between gadgets
* Create list-arrays for gadgets

With Emperor you are generating a complete C/C++-source code, which only must be compiled by an external compiler. Aim of this program is to assure software developer to create their programs (its source code) by Emperor, because the making of software (opening of windows, file- and fontrequests, menus etc.) is often equal and must not longer copied by programmers from other source codes. Emperor decrees about one or more macros for every GUI-element. Like the menus: here you must, for creating the complete Project-menu (open, close, save, print etc.) and its translation, (in Locale-".catalog"-file) only select the corresponding entry in the list. This is also possible with requests e.g. by making a QuitRequest. These are called in the own source code as function "REQUESTNAME();". But the program should also be for Amigans, who never programmed before, and want an easy way in the programming of AmigaOS-GUIs.

[http://os4depot.net/index.php?function=showfile&file=development/guitool/emperor.lha Emperor OS4Depot webpage]

== Free Pascal ==

Free Pascal is a professional Pascal compiler available for AmigaOS that can target many processor architectures.

[https://blog.alb42.de/fpc-amigaos-4/ Free Pascal for AmigaOS webpage]

== adtools GNU Compiler Collection (GCC) ==

The "adtools" project is the Amiga development tools project that hosts a number of tools that can be used for cross-compiling between various platforms and developing applications for AmigaOS and other Amiga-like platforms. The suite is based on the GCC compiler suite.

[https://github.com/sba1/adtools adtools webpage]

== Gui4Cli ==

Gui4Cli is a simple interpreted, event-driven language (no need for previous programming knowledge), which allows you to easily construct great-looking, resizable, font-sensitive GadTools GUIs which (among many other things) can be used to form command lines that can be sent to AmigaDOS or an ARexx port of an other program, for execution. It has many other capabilities too, things like directory & database listviews, maths evaluation, graphics, timers, commodities, file notifications, pipes, appicons etc. etc. With it you can control just about any aspect of the Amiga. Think of it as "Visual DOS".

[http://gui4cli.com/ami/gcmain.htm Gui4Cli webpage]

== Hollywood ==

Hollywood is a multimedia-oriented programming language that can be used to create graphical applications very easily. It was designed with the paradigm to make software creation as easy as possible in mind. Thus, Hollywood is suited for beginners and advanced users alike. Hollywood comes with an extensive function library (encompassing over 800 different commands) that simplifies the creation of games, presentations, and applications, to a great extent. Having been in development since 2002 it is a very mature and stable software package today.

One of the highlights of Hollywood is its inbuilt cross-compiler which can be used to deploy software on many different platforms without having to change a single line of the code. The cross-compiler can compile for all platforms from any platform Hollywood is running on. For instance, you can compile macOS application bundles using the Windows version of Hollywood. There is even an optional add-on that can convert Hollywood applets into stand-alone APKs for release on Android! Android development has never been so easy!

Hollywood is a light-weight, but still powerful programming language whose core is just about two megabytes in size and does not require any external components. Hence, it is ideal for creating programs which run right out of the box. In fact, Hollywood programs will run perfectly from an USB flash drive without any prior installation whatsoever.

Platform architectures currently supported include AmigaOS, Android, iOS, MacOS, Windows, Linux and more.

[https://www.hollywood-mal.com/ Hollywood webpage]

== Lua / LOVE / tolua++ ==

Lua is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description.

Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode with a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal
for configuration, scripting, and rapid prototyping.

LOVE is an awesome framework you can use to make 2D games in Lua. It's free, open-source, and works on Windows, Mac OS X, Linux and AmigaOS.

tolua++ is an extension of toLua, a tool to integrate C/C++ code with Lua. tolua++ includes new features oriented to c++, such as class templates.

tolua is a tool that greatly simplifies the integration of C/C++ code with Lua. Based on a "cleaned" header file, tolua automatically generates the binding code to access C/C++ features from Lua. Using Lua-5.0 API and metamethod facilities, the current version automatically maps C/C++ constants, external variables, functions, namespace, classes, and methods to Lua. It also provides facilities to create Lua modules.

[http://os4depot.net/index.php?function=showfile&file=development/language/liblua.lha Lua OS4Depot webpage]

[http://os4depot.net/index.php?function=showfile&file=development/game/love.lha LOVE OS4Depot webpage]

[http://os4depot.net/index.php?function=showfile&file=development/language/tolua.lha toula++ OS4Depot webpage]

== MUIRexx ==

MUIRexx is a program which serves as an interface between ARexx and MagicUserInterface (MUI). MUIRexx does not provide complete access to all of the capabilities of MagicUserInterface (MUI), however, quite a lot of capability is implemented in MUIRexx such as notification, icon buttons, and application objects (objects that react to icons dropped on them), as well as many standard MUI objects. Complete graphical user interfaces as well as full applications can be developed using MUIRexx and ARexx macros. Additionally, it is also possible to dynamically change or add objects after the application has been created.

[http://aminet.net/package/dev/mui/MUIRexx_3_0a.lha MUIRexx Aminet webpage]

== NoWinED ==

NoWinED is a MUI-based TextEditor that can handle more files simultaneously, using different "pages" for each file. The fact that it is impossible to find a MUI TextEditor on Amiga powerful enough to be used instead of Notepad/Editpad and other editors does not have a reason.

Features:

* Handling of multiple files through tabs that can be managed via titleButtons, a list, and/or an useful context menu which you can open if you click with right mouse button on right scroll titlebutton (this one appears when it's necessary)
* Context menus
* Search and replace module
* Search into opened files module
* File Drag & Drop: dragging one or more files on the NoWinED list the files will be opened in new tabs, dragging a file on a page will open it on the current page. Finally dragging more files on a tab will open the first file in the current tab, and the others in new pages (AROS lacks Drag & Drop)
* Basic texteditor features (C&P, select all, Undo, Redo, etc...).
* Usage from keyboard supported
* UTF support (you can load UTF files and export UTF with/without BOM or ASCII)
* CR/LF/CR+LF support (you can load any kind of txt file and export text with LF/CR/CR+LF)
* Wrapping process of your text at the column you want
* Backup of all opened files (you can set time between a backup process and another one)
* AutoSave of current file (you can set time between a autosave process and another one)
* Programmable Fn keys with independent profiles
* Graphic printout

[http://shinkuro.altervista.org/amiga/software/nowined.htm NoWinED webpage]

== PortablE ==

PortablE is a recreation of the AmigaE programming language, along with many improvements, and the aim of being portable across many platforms.

PortablE works by translating your E code into C++, and then using GCC to compile it into an executable that you can run. But you don't need to worry about these details, because the PEGCC program will handle them for you. PortablE needs an installation of GCC, which is free & easily installed.

[http://cshandley.co.uk/portable/ PortableE webpage]

== ProAction ==

A powerful interface between any Arexx enabled scripting language and the AmigaOS ReAction GUI system. ProAction provides GUIs for script writers, using a unique "dual ARexx Port" approach. ProAction itself is an ARexx host which provides functions for building and managing the GUI, then GUI events are sent as commands to an ARexx port managed by the script.

It can be used from any language that can support an ARexx host. (ARexx (with rexxsupport.libray) python via arexx.so etc etc)

[http://www.broad.ology.org.uk/amiga/proaction/index.html ProAction webpage]

== SDK Browser ==

The SDK Browser provides any Amiga Programmer a quick reference tool into the live AmigaOS Software Development Kit installation on your Amiga, via a 100% graphical (GUI) based tool. It can help you find the format (prototype) for any AmigaOS4.x system call as well as lookup a specific structure reference, method, tag item, what-have-you, quicker than any other tool. Or, you can simply use it as a great way to wander through the AmigaOS4.x development documentation (AutoDocs, Includes, etc.) to learn more about how to program for this great machine and its powerful operating system. There is a great deal of (largely untapped) power available with the "standard" OS if you only know where to look.

Features include:

* Fully multitasking search bar with start/stop and pause/resume. File pattern filter added to search bar, and maintained separately for each search type. Interact with results as they are found, or continue to use all other parts of the SDK Browser as the search continues in the background. Search will continue even when hidden or iconified, and is controllable from the commodity exchange as well.
* History Bar. Quickly return to any of the last 20 items that have been viewed previously. Browse forward or back with the arrow buttons, or pull down and select a new position within the browser history. The history bar works like a combination of a web browser forward and back buttons and a rotating 20 item tabbed display. Giving you the flexibility to quickly work with the last 20 items that have been referenced already.
* Support for more than one interface(API) found within the same library. If the XML file for a given library contains more than one interface for accessing that library, then the SDK Browser will create a new browsable Library tree for each interface and name them with their respective interface name. This is also why the Interface name was added to each library entry under the Library list.
* Faster than ever before using newly optimized viewing routines and less disk access.
* Function calls under "Commands" or an open view of any "Library" now displays just the description of the function call within the AutoDoc instead of displaying the entire AutoDoc and attempting to search for the start of the description. This makes for a cleaner an easier to read display, while the entire AutoDoc file is still instantly available by selecting the Library name itself, or browsing the "AutoDocs" directly.
* Quick find ANY item in the active list just by typing the first few letters of its name.
* New "Includes" browsing. Live browse the system includes using the new embedded directory scanner.
* Convenient "Send To" menu for launching a helpful set of external viewers right from the SDK Browser. Quickly open source files into the editor of your choice, or open HTML files directly into your web browser of choice. You can also launch the currently selected file with "MultiView", "AmiPDF", or even "Unarc" those archives.
* Improved interface handles all Library, Commands, AutoDocs, and Includes browsing under the "SDK" clicktab, while also giving the user a "Project" tab and directory scan lister for browsing their own project source or any where you need to, quickly and easily from one tool.
* Extensive keyboard controls to enhance the existing "mouse-over" focused movement keys and "mouse-wheel" support.
* Programmable SDK and search paths.
* Programmable EDITOR and WEBBROWSER tooltypes for use by the "Send To" menu.

[http://bitbybitsoftwaregroup.com/sdkbrowser/index.php SDK Browser webpage]

== vbcc ==

vbcc is a highly optimizing portable and retargetable ISO C compiler available for AmigaOS. It supports ISO C according to ISO/IEC 9899:1989 and a subset of the new standard ISO/IEC 9899:1999 (C99).

[http://sun.hasenbraten.de/vbcc/ vbcc webpage]

== Vim ==

Vim is a highly configurable text editor built to make creating and changing any kind of text very efficient. Vim is rock stable and is continuously being developed to become even better. Among its features are:

* persistent, multi-level undo tree
* extensive plugin system
* support for hundreds of programming languages and file formats
* powerful search and replace
* integrates with many tools

Please note that this is not a straight port of the upstream version. It includes a full MUI GUI with most of the bells and whistles found in Vim on any of the major platforms. "TheBar" custom class must be installed for MUI for this version of Vim.

[https://sourceforge.net/projects/spaden/ AmigaOS Vim webpage]

[https://github.com/amiga-mui/thebar TheBar custom class webpage]

AmigaOS Apps Games

2019-03-10T21:51:15Z

Paul Sadlik: /* Neverball */

The following is a sampling of games you might enjoy on AmigaOS4.

=== Disclaimer ===
The following list of applications are neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

== Aquaria ==

A massive ocean world, teeming with life and filled with ancient secrets.

Join Naija, a lone underwater dweller in search of her family, as she explores the depths of Aquaria.

She'll travel from hidden caves, shrouded in darkness, to beautiful, sunlit oases, all lovingly handcrafted by its two creators.

Naija's story, narrated fully with voice overs, will become yours, as you join her on this magnificent adventure.

[https://www.amigasoft.net/aquaria/ Amigasoft game webpage]

== Ask Me Up XXL ==

Ask Me Up XXL is a video game about general knowledge.

The principle is quite simple: 1 question, 4 possible answers ...

Choose the right one!

You know all celebrities' secrets? You can easily put a city on a map. You know who is the first white sprinter to have officially run 100m in under 10 seconds? Or you have no idea about it?

In all cases, our quiz is for you and you will learn while having fun! Play alone or with others, share your high scores with your friends, check your statistics to analyze progress ... All this is possible!

[http://glames.online.fr/products/askmeup_xxl.html Boing Attitude game webpage]

== Descent Freespace: The Great War ==

FreeSpace takes place in a fictional future where humans have discovered how to travel long distances by jumping into subspace, and have spread among the stars as the Galactic Terran Alliance (GTA).

Descent: FreeSpace The Great War puts the player in starfighter flying out on missions to investigate, protect, or destroy certain targets. Some have categorized it as a flight simulator, since it has more controls and commands than a typical arcade game. In the single-player mode, the player flies through a series of missions in a campaign.

The game features multiplayer matches online or over a local area network (LAN). Players can either band together to complete cooperative missions, or split up into teams to battle against one another.

[http://www.hyperion-entertainment.com/index.php/where-to-buy/direct-downloads/182-descent-freespace-amigaos Descent Freespace: The Great War game webpage]

== Digital Universe for AmigaOS ==

Digital Universe, a highly sophisticated planetarium software package, is available for AmigaOS.

[http://www.digitaluniverse.org.uk Digital Universe webpage]

== Gorky 17 ==

Gorky 17 is a horror conspiracy game mixing elements of strategy and RPG gameplay. You, the player, command a small group of NATO soldiers who must reveal the mystery behind the sudden appearance of hybrid creatures in a small Polish city named Lubin.

The city is being terrorized, the area is surrounded by NATO troops and media from all over the world, and the first group sent into the city disappears without a trace.

The main hero of the story is the 40-year old soldier Cole Sullivan, a commando team member with extensive scientific knowledge. His team`s task: to explain the hybrids` presence and to find the missing members of Group One. But that, of course, is just the beginning...

It is your task to discover the secrets behind Gorky 17.

[http://www.hyperion-entertainment.com/index.php/games/gorky-17 Gorky 17 game webpage]

== Neverball ==

Neverball sees you guide a ball through a series of complex grids and courses with the aim of either collecting as much cash as you can, beating a time limit or reaching a certain goal. You guide the ball by tilting the course side to side but one false move either way sees you fall to your death!

There are many courses to choose from to challenge your skills and reactions, there are also a selection of in-game challenges as well that you may want to attempt. Controlling the ball in Neverball is extremely tricky at times. You'll need to home your skills to make sure your ball doesn't just roll off the edge, hit a barrier or simply run out of control. It can take several goes before you can even complete one course on the easy level, this game will keep you coming back for more.

If you've got the patience to guide a ball through some seemingly impossible levels you'll enjoy Neverball.

[http://www.os4depot.net/index.php?function=showfile&file=game/misc/neverball-bin.lha Neverball OS4Depot page]

== Nexuiz ==

Nexuiz is a fast paced 3D deathmatch game project created online by a team of developers called Alientrap.

It is available for download for Amiga, Windows, Mac, and Linux (all in the same archive).

The first version was released May 31st 2005, released entirely GPL and free over the net, a first for a project of its kind. Since then it has been downloaded over 1.5 million times, and the game is still being updated and developed, currently at version 2.5 and new releases being developed.

[https://www.amigasoft.net/download-games/ Amigasoft game webpage]

== Swamp Defense 2 ==

Fight countless enemies with a huge selection of gun turrets (in the form of comic heroes) and
additional helpers (mines, air support, block wall) on more than 60 maps. Earn
coins to obtain improvements in the integrated shop system and to buy new towers.

Features:

* Shop system for buying and improving towers and for purchasing special weapons
* 9 defense towers, capable of improvement (2 improvements each within a battle)
* Support towers, special attacks and elements that can be placed along the path
* Unique opponents - 54 unlockable maps + 9 bonus maps
* Tower control (control of direction and aim of a tower)
* Weapons: pistol, electron beam, fire fart, adhesive cream, skillet, rocket launcher, dynamite, lethal injection, electric nail gun
* Power-up for each tower: damage, rate of fire, range can be placed along the path: mine, adhesive cream fence, block wall
* Supporters: fire power expansion, range expansion
* Overall assistance: area bomb, atomic bomb, air support
* Global Help in game: F1

[http://www.amiboing.de/gameDetail.php?id=20 AmiBoing game webpage]

== Tower 57 ==

In a dystopian, dieselpunk world, where Megatowers are the only enclaves of civilization, a group of extraordinary individuals is sent to infiltrate the reclusive Tower 57. Their skills, clips' capacity & the ability to cooperate will decide on their fate.

Tower 57 is a TOP-DOWN TWIN STICK SHOOTER with 16-bit inspired pixel art, destructible environments and heavy focus on CO-OP. It is also a modern take on what made AMIGA games so great back in the days.

[https://benitosub.itch.io/tower-57 Tower 57 game webpage]

AmigaOS Apps Games

2019-03-10T21:47:34Z

Paul Sadlik: /* Aquaria */

The following is a sampling of games you might enjoy on AmigaOS4.

=== Disclaimer ===
The following list of applications are neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

== Aquaria ==

A massive ocean world, teeming with life and filled with ancient secrets.

Join Naija, a lone underwater dweller in search of her family, as she explores the depths of Aquaria.

She'll travel from hidden caves, shrouded in darkness, to beautiful, sunlit oases, all lovingly handcrafted by its two creators.

Naija's story, narrated fully with voice overs, will become yours, as you join her on this magnificent adventure.

[https://www.amigasoft.net/aquaria/ Amigasoft game webpage]

== Ask Me Up XXL ==

Ask Me Up XXL is a video game about general knowledge.

The principle is quite simple: 1 question, 4 possible answers ...

Choose the right one!

You know all celebrities' secrets? You can easily put a city on a map. You know who is the first white sprinter to have officially run 100m in under 10 seconds? Or you have no idea about it?

In all cases, our quiz is for you and you will learn while having fun! Play alone or with others, share your high scores with your friends, check your statistics to analyze progress ... All this is possible!

[http://glames.online.fr/products/askmeup_xxl.html Boing Attitude game webpage]

== Descent Freespace: The Great War ==

FreeSpace takes place in a fictional future where humans have discovered how to travel long distances by jumping into subspace, and have spread among the stars as the Galactic Terran Alliance (GTA).

Descent: FreeSpace The Great War puts the player in starfighter flying out on missions to investigate, protect, or destroy certain targets. Some have categorized it as a flight simulator, since it has more controls and commands than a typical arcade game. In the single-player mode, the player flies through a series of missions in a campaign.

The game features multiplayer matches online or over a local area network (LAN). Players can either band together to complete cooperative missions, or split up into teams to battle against one another.

[http://www.hyperion-entertainment.com/index.php/where-to-buy/direct-downloads/182-descent-freespace-amigaos Descent Freespace: The Great War game webpage]

== Digital Universe for AmigaOS ==

Digital Universe, a highly sophisticated planetarium software package, is available for AmigaOS.

[http://www.digitaluniverse.org.uk Digital Universe webpage]

== Gorky 17 ==

Gorky 17 is a horror conspiracy game mixing elements of strategy and RPG gameplay. You, the player, command a small group of NATO soldiers who must reveal the mystery behind the sudden appearance of hybrid creatures in a small Polish city named Lubin.

The city is being terrorized, the area is surrounded by NATO troops and media from all over the world, and the first group sent into the city disappears without a trace.

The main hero of the story is the 40-year old soldier Cole Sullivan, a commando team member with extensive scientific knowledge. His team`s task: to explain the hybrids` presence and to find the missing members of Group One. But that, of course, is just the beginning...

It is your task to discover the secrets behind Gorky 17.

[http://www.hyperion-entertainment.com/index.php/games/gorky-17 Gorky 17 game webpage]

== Neverball ==

Neverball sees you guide a ball through a series of complex grids and courses with the aim of either collecting as much cash as you can, beating a time limit or reaching a certain goal. You guide the ball by tilting the course side to side but one false move either way sees you fall to your death!

There are many courses to choose from to challenge your skills and reactions, there are also a selection of in-game challenges as well that you may want to attempt. Controlling the ball in Neverball is extremely tricky at times. You'll need to home your skills to make sure your ball doesn't just roll off the edge, hit a barrier or simply run out of control. It can take several goes before you can even complete one course on the easy level, this game will keep you coming back for more.

If you've got the patience to guide a ball through some seemingly impossible levels you'll enjoy Neverball.

[http://www.os4depot.net/share/game/misc/neverball-bin.lha Neverball download]

== Nexuiz ==

Nexuiz is a fast paced 3D deathmatch game project created online by a team of developers called Alientrap.

It is available for download for Amiga, Windows, Mac, and Linux (all in the same archive).

The first version was released May 31st 2005, released entirely GPL and free over the net, a first for a project of its kind. Since then it has been downloaded over 1.5 million times, and the game is still being updated and developed, currently at version 2.5 and new releases being developed.

[https://www.amigasoft.net/download-games/ Amigasoft game webpage]

== Swamp Defense 2 ==

Fight countless enemies with a huge selection of gun turrets (in the form of comic heroes) and
additional helpers (mines, air support, block wall) on more than 60 maps. Earn
coins to obtain improvements in the integrated shop system and to buy new towers.

Features:

* Shop system for buying and improving towers and for purchasing special weapons
* 9 defense towers, capable of improvement (2 improvements each within a battle)
* Support towers, special attacks and elements that can be placed along the path
* Unique opponents - 54 unlockable maps + 9 bonus maps
* Tower control (control of direction and aim of a tower)
* Weapons: pistol, electron beam, fire fart, adhesive cream, skillet, rocket launcher, dynamite, lethal injection, electric nail gun
* Power-up for each tower: damage, rate of fire, range can be placed along the path: mine, adhesive cream fence, block wall
* Supporters: fire power expansion, range expansion
* Overall assistance: area bomb, atomic bomb, air support
* Global Help in game: F1

[http://www.amiboing.de/gameDetail.php?id=20 AmiBoing game webpage]

== Tower 57 ==

In a dystopian, dieselpunk world, where Megatowers are the only enclaves of civilization, a group of extraordinary individuals is sent to infiltrate the reclusive Tower 57. Their skills, clips' capacity & the ability to cooperate will decide on their fate.

Tower 57 is a TOP-DOWN TWIN STICK SHOOTER with 16-bit inspired pixel art, destructible environments and heavy focus on CO-OP. It is also a modern take on what made AMIGA games so great back in the days.

[https://benitosub.itch.io/tower-57 Tower 57 game webpage]

AmigaOS Applications

2019-03-10T18:39:03Z

Paul Sadlik: /* Disclaimer */

=== Disclaimer ===
The following list of applications are neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

= Applications =

[[AmigaOS Apps Games|Games]] - Games on AmigaOS4

AmigaOS Apps Games

2019-03-10T18:37:22Z

Paul Sadlik: /* Ask Me Up XXL */

The following is a sampling of games you might enjoy on AmigaOS4.

=== Disclaimer ===
The following list of applications are neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

== Ask Me Up XXL ==

Ask Me Up XXL is a video game about general knowledge.

The principle is quite simple: 1 question, 4 possible answers ...

Choose the right one!

You know all celebrities' secrets? You can easily put a city on a map. You know who is the first white sprinter to have officially run 100m in under 10 seconds? Or you have no idea about it?

In all cases, our quiz is for you and you will learn while having fun! Play alone or with others, share your high scores with your friends, check your statistics to analyze progress ... All this is possible!

[http://glames.online.fr/products/askmeup_xxl.html Boing Attitude game webpage]

== Swamp Defense 2 ==

Fight countless enemies with a huge selection of gun turrets (in the form of comic heroes) and
additional helpers (mines, air support, block wall) on more than 60 maps. Earn
coins to obtain improvements in the integrated shop system and to buy new towers.

Features:

* Shop system for buying and improving towers and for purchasing special weapons
* 9 defense towers, capable of improvement (2 improvements each within a battle)
* Support towers, special attacks and elements that can be placed along the path
* Unique opponents - 54 unlockable maps + 9 bonus maps
* Tower control (control of direction and aim of a tower)
* Weapons: pistol, electron beam, fire fart, adhesive cream, skillet, rocket launcher, dynamite, lethal injection, electric nail gun
* Power-up for each tower: damage, rate of fire, range can be placed along the path: mine, adhesive cream fence, block wall
* Supporters: fire power expansion, range expansion
* Overall assistance: area bomb, atomic bomb, air support
* Global Help in game: Fl

[http://www.amiboing.de/gameDetail.php?id=20 AmiBoing game webpage]

AmigaOS Apps Games

2019-03-10T18:36:51Z

Paul Sadlik: /* Disclaimer */

The following is a sampling of games you might enjoy on AmigaOS4.

=== Disclaimer ===
The following list of applications are neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

== Ask Me Up XXL ==

Ask Me Up XXL is a video game about general knowledge.

The principle is quite simple: 1 question, 4 possible answers ...

Choose the right one!

You know all celebrities' secrets? You can easily put a city on a map. You know who is the first white sprinter to have officially run 100m in under 10 seconds? Or you have no idea about it?

In all cases, our quiz is for you and you will learn while having fun! Play alone or with others, share your high scores with your friends, check your statistics to analyze progress ... All this is possible!

[http://glames.online.fr/products/askmeup_xxl.html Boing Attitude game webpage]

== Swamp Defense 2 ==

Fight countless enemies with a huge selection of gun turrets (in the form of comic heroes) and
additional helpers (mines, air support, block wall) on more than 60 maps. Earn
coins to obtain improvements in the integrated shop system and to buy new towers.

Features:

* Shop system for buying and improving towers and for purchasing special weapons
* 9 defense towers, capable of improvement (2 improvements each within a battle)
* Support towers, special attacks and elements that can be placed along the path
* Unique opponents - 54 unlockable maps + 9 bonus maps
* Tower control (control of direction and aim of a tower)
* Weapons: pistol, electron beam, fire fart, adhesive cream, skillet, rocket launcher, dynamite, lethal injection, electric nail gun
* Power-up for each tower: damage, rate of fire, range can be placed along the path: mine, adhesive cream fence, block wall
* Supporters: fire power expansion, range expansion
* Overall assistance: area bomb, atomic bomb, air support
* Global Help in game: Fl

[http://www.amiboing.de/gameDetail.php?id=20 AmiBoing game webpage]

AmigaOS Apps Games

2019-03-10T18:27:04Z

Paul Sadlik:

The following is a sampling of games you might enjoy on AmigaOS4.

= Disclaimer =
The following list of applications are neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

== Ask Me Up XXL ==

Ask Me Up XXL is a video game about general knowledge.

The principle is quite simple: 1 question, 4 possible answers ...

Choose the right one!

You know all celebrities' secrets? You can easily put a city on a map. You know who is the first white sprinter to have officially run 100m in under 10 seconds? Or you have no idea about it?

In all cases, our quiz is for you and you will learn while having fun! Play alone or with others, share your high scores with your friends, check your statistics to analyze progress ... All this is possible!

[http://glames.online.fr/products/askmeup_xxl.html Boing Attitude game webpage]

== Swamp Defense 2 ==

Fight countless enemies with a huge selection of gun turrets (in the form of comic heroes) and
additional helpers (mines, air support, block wall) on more than 60 maps. Earn
coins to obtain improvements in the integrated shop system and to buy new towers.

Features:

* Shop system for buying and improving towers and for purchasing special weapons
* 9 defense towers, capable of improvement (2 improvements each within a battle)
* Support towers, special attacks and elements that can be placed along the path
* Unique opponents - 54 unlockable maps + 9 bonus maps
* Tower control (control of direction and aim of a tower)
* Weapons: pistol, electron beam, fire fart, adhesive cream, skillet, rocket launcher, dynamite, lethal injection, electric nail gun
* Power-up for each tower: damage, rate of fire, range can be placed along the path: mine, adhesive cream fence, block wall
* Supporters: fire power expansion, range expansion
* Overall assistance: area bomb, atomic bomb, air support
* Global Help in game: Fl

[http://www.amiboing.de/gameDetail.php?id=20 AmiBoing game webpage]

AmigaOS Apps Games

2019-03-10T18:22:19Z

Paul Sadlik: Created page with " The following is a sampling of games you might enjoy on AmigaOS4. = Disclaimer = The following list of applications are neither endorsed by nor supported by Hyperion Enterta..."

The following is a sampling of games you might enjoy on AmigaOS4.

= Disclaimer =
The following list of applications are neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

== Swamp Defense 2 ==

Fight countless enemies with a huge selection of gun turrets (in the form of comic heroes) and
additional helpers (mines, air support, block wall) on more than 60 maps. Earn
coins to obtain improvements in the integrated shop system and to buy new towers.

Features:

* Shop system for buying and improving towers and for purchasing special weapons
* 9 defense towers, capable of improvement (2 improvements each within a battle)
* Support towers, special attacks and elements that can be placed along the path
* Unique opponents - 54 unlockable maps + 9 bonus maps
* Tower control (control of direction and aim of a tower)
* Weapons: pistol, electron beam, fire fart, adhesive cream, skillet, rocket launcher, dynamite, lethal injection, electric nail gun
* Power-up for each tower: damage, rate of fire, range can be placed along the path: mine, adhesive cream fence, block wall
* Supporters: fire power expansion, range expansion
* Overall assistance: area bomb, atomic bomb, air support
* Global Help in game: Fl

[http://www.amiboing.de/gameDetail.php?id=20 AmiBoing Swamp Defense 2 webpage]

AmigaOS Applications

2019-03-10T18:12:35Z

Paul Sadlik: /* Applications */

= Disclaimer =
The following list of applications are neither endorsed by nor supported by Hyperion Entertainment. This list is strictly informational only.

= Applications =

[[AmigaOS Apps Games|Games]] - Games on AmigaOS4

UserDoc:Main

2018-01-12T03:32:39Z

Paul Sadlik: /* AmigaOS platform targets */

== Welcome to AmigaOS ==

AmigaOS was born in 1985 and delivered what contemporary personal computer operating systems could only dream of. As the first "multimedia" operating system, it was trivial for AmigaOS computers to display animations while playing music and reading data from disks. Such multimedia and multitasking finesse drew many people to this system. Some of them are famous: [http://www.amigahistory.co.uk/warhol.html Andy Warhol], Sir Arthur C. Clarke, [http://www.polyphoto.com/upchug/AEcastro.html NASA], Hollywood and the TV broadcasting industry, and many others that thought [http://www.youtube.com/watch?v=PWeO5IkCssk only Amiga makes it possible].

Today many people still think AmigaOS has something special that makes it more interesting and rewarding than other systems. This system allows the user to control the computer, not the other way around. It is a system you fully understand that is easier and more flexible to use. In other words, AmigaOS is '''more fun'''.

=== AmigaOS: The flexible operating system ===
AmigaOS is an operating system: a collection of efficient programs written to start the computer, let the user control the computer, and present feedback to the user.

AmigaOS is designed with ease of use and flexibility in mind. To begin with, AmigaOS provides a clear view of your computer, your applications and files. A number of methods are available to let your computer serve you, whether graphically with a mouse, using the "Shell" command line, or by some other means the user prefers.

AmigaOS strives to avoid stupid limitations that can be found on other systems. AmigaOS users can organise their files the way they like. There are few limits on file hierarchy, locations and file names. Drives don't have to be named with a letter or cryptic names (such as C:, or sda1), your files don't have to reside in your "Documents" folder and your hard drives aren't hidden from you. If you're not writing to drives and you want to "shut down", why wait for the OS to allow that? With AmigaOS, just hit the power switch. Done.

An Amiga does not start with pre-installed applications serving some sales conglomerate, marketing organization or their big brother. AmigaOS does not do actions behind the user's back. As unique as it is today, the AmigaOS computer serves the user and not the other way around. With one of the largest proportions of user-programmers around, the trustworthy AmigaOS user-friendly ethic is mirrored in AmigaOS applications.

Since the first versions more than twenty-five years ago, AmigaOS has also been designed to serve efficiently. Optimizing applications and OS code has always been the goal of programmers and developers of this operating system. The result is an operating system and applications that take less space on your hard drives, waste less time loading, consume less memory, require less processing power, and respond more quickly to the user.

And every update of AmigaOS doesn't demand you must buy newer, more powerful hardware. AmigaOS currently runs on twenty year old 200MHz computers or brand new dual core 1,800MHz computers. It's the user's choice how they want to '''enjoy''' AmigaOS.

=== Some AmigaOS features ===
Here are some of the features of AmigaOS that make it easy to control your computer. Some of these concepts were copied by other operating systems which tend to show they are the correct way of doing things.

* '''Small footprint:''' AmigaOS can work with 64 MB of memory. On disk, a default installation only takes around 200 MB. The smaller footprint translates into a more responsive user experience given any hardware.

* '''Straightforward operating system design:''' With a clear layout and easy to understand names (Classes, Libs, Fonts, Prefs, Storage, etc.), you can easily understand what everything in AmigaOS is and what it does for you. Nothing is hidden from the user and the user is not restricted by AmigaOS.

*'''User configurable graphic interface:''' Using the provided "preferences editors," the user can dramatically reconfigure how AmigaOS looks, sounds, runs and responds to every user whim.

* '''File recognition based on file content:''' You can name a file '''whatever you want''', even without an extension. Examples: "my file" or "picture of Jay in Santa Clara". There is no need to add an extension to explain what the file is, like ".txt" or ".jpg". AmigaOS really examines the '''file content''' to recognise what type of file it is.

* '''Logical assignments:''' Easily set and use logical names names for directories located anywhere on your system. For example, "Auto:" can point to your directory "car show pictures" buried on your media drive.

* '''Ram disk concept:''' On AmigaOS there is a special disk called the '''Ram disk''' which represents a part of your computer memory. This area is not fixed. It automatically grows whenever you store files in it. For example, it's a great place to unpack files to install from there, greatly speeding up the installation.

* '''Command line and graphical user interfaces:''' Both the the graphical user interface (GUI) and command line interface (where you type commands into a window with the keyboard) can be used to manage AmigaOS, its programs and files. Both interfaces are intergated with each other so you can easily use command lines from the GUI or open graphical elements from a command line.

*'''ARexx Ports:''' Throughout AmigaOS and third party programs, "ARexx" message ports let one application talk with others so that apps work together to serve the user. AmigaOS also provides the lightweight ARexx and modern Python programming languages that can control AmigaOS and applications with ARexx ports.

* '''Resident Commands:''' Commands can be made resident, i.e., they are kept in memory so that they can be reused with no loading time.

* '''Restart only the operating system:''' if you feel the need to restart the system, you can do so by restarting '''only AmigaOS''' and not the whole computer.

=== AmigaOS platform targets ===

While the original versions of AmigaOS ran on computers of the eighties using Motorola 68k series CPU chips, the current AmigaOS runs on computers using PowerPC processor chips [http://www.amigaos.net/content/72/supported-hardware hardware]. These can be older Amiga computers (also called "Classic Amigas") with PPC "accelerator cards" or new generation Amiga PPC computers.

In this guide, we will concentrate on the current AmigaOS running on the supported hardware:

* [[AmigaOne A1222]] model by [http://www.a-eon.com A-Eon Technology]

* [[AmigaOne X5000]] model by [http://www.a-eon.com A-Eon Technology]

* [[AmigaOne X1000]] model by [http://www.a-eon.com A-Eon Technology]

* [[AmigaOne 500]], Sam460, Sam440ep and Sam440-flex models by [http://www.acube-systems.com ACube Systems]

* [[Pegasos II]] model by [http://www.bplan-gmbh.de bplan GmbH]

* [[AmigaOne XE and MicroA1-C]] models by [http://en.wikipedia.org/wiki/Eyetech Eyetech Group Ltd].

* [[Classic Amiga]] 4000(T), 3000(T) and 1200 models by Commodore Business Machines (when equipped with PowerPC accelerator cards).

== How does AmigaOS work? - Concepts ==

In this page we will discuss [[UserDoc:How AmigaOS Works|how AmigaOS works]]:

* [[UserDoc:How_AmigaOS_Works#The_most_important_components|The most important components]] (Exec, AmigaDOS, Intuition...)
* [[UserDoc:How_AmigaOS_Works#How_is_my_data_stored.3F|how files and data are stored]]
* [[UserDoc:How_AmigaOS_Works#All_AmigaOS_components|all AmigaOS components are described]]
* [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|how AmigaOS is booted on your Amiga computer]]
* [[Workbench/Prefs|AmigaOS settings programs]]
* ...

== How to use AmigaOS? ==

AmigaOS is a collection of components that oversee the computer hardware & data and provide the user with easy, understandable tools to manage and use them.

In the following [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS pages]] we will discuss the basic concepts:

* how to use AmigaOS
* what the AmigaOS graphic user interface is composed of
* what interfaces AmigaOS provides, including the [[UserDoc:Workbench|Workbench]], the [[UserDoc:Shell|Shell]] or scripting languages.

From the introduction page, you can continue with more detailed pages on the [[UserDoc:Workbench|Workbench]] and the [[AmigaDOS manual]] . Now let's start with this [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS]].

== Manuals ==

[[UserDoc:AmigaOS File Systems|AmigaOS File Systems]] - AmigaOS File Systems

[[AmigaOS Manual]] - AmigaOS Manual

[[Bars & Pipes Professional]] - MIDI Sequencer

DeveloperDoc:Main

2017-01-22T20:18:03Z

Paul Sadlik: /* Introduction */

== Introduction ==

Many programming languages can be used on AmigaOS. They range from scripting languages to comprehensive compiled langauges:

* [[AmigaOS Manual: ARexx|ARexx]]: the native AmigaOS scripting language, good for beginners,small projects and talking between applications.
* Python: a common cross platform scripting language ported to & included with AmigaOS.
* C: the primary compiled language for AmigaOS.
* [https://aglet.web.runbox.net/ Modula2]: the compiled language that evolved from Pascal.
* [http://cshandley.co.uk/portable/PortablE.html E]: an Amiga native compiled language.

ARexx is built into AmigaOS and its original documentation can be found in [[AmigaOS Manual: ARexx|this part]] of the Developer's Wiki.

A native compiler for the C language is part of the downloadable [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS SDK].

Most of the remaining AmigaOS Developers Wiki provides the latest information on how to program systems running AmigaOS 4.x with the C language. It has been updated for Release 4.0 and higher of AmigaOS and covers all the computer systems which run the Amiga operating system from the Commodore A1200 all the way up to the AmigaOne X5000..

The Wiki assumes some previous experience with programming and familiarity with computers in general. Although it is not required, a knowledge of the C programming language will make it much easier to understand the material in this book. Most of the Amiga operating system is written in C, hence C is the language used for the programming examples.

Many of the AmigaOS concepts, methods described in the wiki for C will also be applicable to other compiled languages, with some variations. Please see the documentation of the respective languages.

This wiki is intended for the following audiences:

* Programmers who want to create application software for AmigaOS systems.
* Software developers who want to upgrade their software for Release 4.0 or higher of the operating system.
* Anyone who wants to know more about how AmigaOS works.

The system software is organized into related groups of functions called libraries. The same basic organization is used for this wiki.

== Software Development Kit (SDK) ==

You can find the [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS SDK at this location].

[[SDK Release Notes|Release Notes]]

[[SDK FAQ|Frequency Asked Questions]]

[[Autodocs:Main|Autodocs]]

[[Fundamental Types]]

== Reference ==

[[Kernel]]

[[Libraries]]

[[Devices]]

[[Resources]]

[[User Interface Style Guide]]

== General Information ==

[[AmigaOS Versions]]

[[Controlling Application Stack]]

[[GUI Programming]]

[[Programming in the Amiga Environment]]

[[Libraries and Devices]]

[[Migration Guide]]

[[Troubleshooting Your Software]]

[[Understanding the alert error numbers]]

[[Release 4 Compatibility]]

[[Writing apps for Xena]]

[[AmigaGuide 101]]

[[Installation Utility]]

[[Optimized Window Refreshing]]

[[Autodoc Style Guide]]

[[Debug Kernel]]

[[AmiDock and Dockies]]

[[Command Line Interface]]

[[DCFS and LNFS Low Level Data Structures]]

DeveloperDoc:Main

2017-01-22T20:11:44Z

Paul Sadlik: /* Introduction */

== Introduction ==

Many programming languages can be used on AmigaOS. They range from scripting languages to comprehensive compiled langauges:

* [[AmigaOS Manual: ARexx|ARexx]]: the native AmigaOS scripting language, good for beginners,small projects and talking between applications.
* Python: a common cross platform scripting language ported to & included with AmigaOS.
* C: the primary compiled language for AmigaOS.
* [https://aglet.web.runbox.net/ Modula2]: the compiled language that evolved from Pascal.
* [http://cshandley.co.uk/portable/PortablE.html E]: an Amiga native compiled language.

ARexx is built into AmigaOS and its original documentation can be found in [[AmigaOS Manual: ARexx|this part]] of the Developer's Wiki.

A native compiler for the C language is part of the downloadable [http://www.amigaos.net/content/81/sdk AmigaOS SDK].

Most of the remaining AmigaOS Developers Wiki provides the latest information on how to program systems running AmigaOS 4.x with the C language. It has been updated for Release 4.0 and higher of AmigaOS and covers all the computer systems which run the Amiga operating system from the Commodore A1200 all the way up to the AmigaOne X5000..

The Wiki assumes some previous experience with programming and familiarity with computers in general. Although it is not required, a knowledge of the C programming language will make it much easier to understand the material in this book. Most of the Amiga operating system is written in C, hence C is the language used for the programming examples.

Many of the AmigaOS concepts, methods described in the wiki for C will also be applicable to other compiled languages, with some variations. Please see the documentation of the respective languages.

This wiki is intended for the following audiences:

* Programmers who want to create application software for AmigaOS systems.
* Software developers who want to upgrade their software for Release 4.0 or higher of the operating system.
* Anyone who wants to know more about how AmigaOS works.

The system software is organized into related groups of functions called libraries. The same basic organization is used for this wiki.

== Software Development Kit (SDK) ==

You can find the [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS SDK at this location].

[[SDK Release Notes|Release Notes]]

[[SDK FAQ|Frequency Asked Questions]]

[[Autodocs:Main|Autodocs]]

[[Fundamental Types]]

== Reference ==

[[Kernel]]

[[Libraries]]

[[Devices]]

[[Resources]]

[[User Interface Style Guide]]

== General Information ==

[[AmigaOS Versions]]

[[Controlling Application Stack]]

[[GUI Programming]]

[[Programming in the Amiga Environment]]

[[Libraries and Devices]]

[[Migration Guide]]

[[Troubleshooting Your Software]]

[[Understanding the alert error numbers]]

[[Release 4 Compatibility]]

[[Writing apps for Xena]]

[[AmigaGuide 101]]

[[Installation Utility]]

[[Optimized Window Refreshing]]

[[Autodoc Style Guide]]

[[Debug Kernel]]

[[AmiDock and Dockies]]

[[Command Line Interface]]

[[DCFS and LNFS Low Level Data Structures]]

DeveloperDoc:Main

2017-01-22T20:09:08Z

Paul Sadlik: /* Introduction */

== Introduction ==

Many programming languages can be used on AmigaOS. They range from scripting languages to comprehensive compiled langauges:

* [[AmigaOS Manual: ARexx|ARexx]]: the native AmigaOS scripting language, good for beginners,small projects and talking between applications.
* Python: a common cross platform scripting language ported to & included with AmigaOS.
* C: the primary compiled language for AmigaOS.
* [https://aglet.web.runbox.net/ Modula2]: the compiled language that evolved from Pascal.
* [http://cshandley.co.uk/portable/PortablE.html E]: an Amiga native compiled language.

ARexx is built into AmigaOS and its original documentation can be found in [[AmigaOS Manual: ARexx|this part]] of the Developer's Wiki.

The C language is part of the downloadable [http://www.amigaos.net/content/81/sdk AmigaOS SDK].

Most of the remaining AmigaOS Developers Wiki provides the latest information on how to program systems running AmigaOS 4.x with the C language. It has been updated for Release 4.0 and higher of AmigaOS and covers all the computer systems which run the Amiga operating system from the Commodore A1200 all the way up to the AmigaOne X5000..

The Wiki assumes some previous experience with programming and familiarity with computers in general. Although it is not required, a knowledge of the C programming language will make it much easier to understand the material in this book. Most of the Amiga operating system is written in C, hence C is the language used for the programming examples.

Many of the AmigaOS concepts, methods described in the wiki for C will also be applicable to other compiled languages, with some variations. Please see the documentation of the respective languages.

This wiki is intended for the following audiences:

* Programmers who want to create application software for AmigaOS systems.
* Software developers who want to upgrade their software for Release 4.0 or higher of the operating system.
* Anyone who wants to know more about how AmigaOS works.

The system software is organized into related groups of functions called libraries. The same basic organization is used for this wiki.

== Software Development Kit (SDK) ==

You can find the [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS SDK at this location].

[[SDK Release Notes|Release Notes]]

[[SDK FAQ|Frequency Asked Questions]]

[[Autodocs:Main|Autodocs]]

[[Fundamental Types]]

== Reference ==

[[Kernel]]

[[Libraries]]

[[Devices]]

[[Resources]]

[[User Interface Style Guide]]

== General Information ==

[[AmigaOS Versions]]

[[Controlling Application Stack]]

[[GUI Programming]]

[[Programming in the Amiga Environment]]

[[Libraries and Devices]]

[[Migration Guide]]

[[Troubleshooting Your Software]]

[[Understanding the alert error numbers]]

[[Release 4 Compatibility]]

[[Writing apps for Xena]]

[[AmigaGuide 101]]

[[Installation Utility]]

[[Optimized Window Refreshing]]

[[Autodoc Style Guide]]

[[Debug Kernel]]

[[AmiDock and Dockies]]

[[Command Line Interface]]

[[DCFS and LNFS Low Level Data Structures]]

DeveloperDoc:Main

2017-01-22T19:54:35Z

Paul Sadlik: /* Introduction */

== Introduction ==

Many programming languages can be used on AmigaOS. They range from scripting languages to comprehensive compiled langauges:

* ARexx: the native AmigaOS scripting language, good for beginners,small projects and talking between applications.
* Python: a common cross platform scripting language ported to & included with AmigaOS.
* C: the most comprehensive compiled language for AmigaOS.
* [http://home.ntelos.net/~tbreeden/ Modula-2]: the compiled language that evolved from Pascal.
* [http://cshandley.co.uk/portable/PortablE.html E]: an Amiga native compiled language.

The C language is the primary compiled programming language of the Amiga and is available in the Amiga [http://www.amigaos.net/content/81/sdk SDK]. The original documentation for ARexx is available in the Wiki here and still applies to the latest versions of AmigaOS4.

Most of the AmigaOS Developers Wiki provides the latest information on how to program systems running AmigaOS 4.x with the C language. It has been updated for Release 4.0 and higher of AmigaOS and covers all the computer systems which run the Amiga operating system from the Commodore A1200 all the way up to the AmigaOne X5000..

The Wiki assumes some previous experience with programming and familiarity with computers in general. Although it is not required, a knowledge of the C programming language will make it much easier to understand the material in this book. Most of the Amiga operating system is written in C, hence C is the language used for the programming examples.

Many of the AmigaOS concepts, methods described in the wiki for C will also be applicable to other compiled languages, with some variations. Please see the documentation of the respective languages.

This wiki is intended for the following audiences:

* Programmers who want to create application software for AmigaOS systems.
* Software developers who want to upgrade their software for Release 4.0 or higher of the operating system.
* Anyone who wants to know more about how AmigaOS works.

The system software is organized into related groups of functions called libraries. The same basic organization is used for this wiki.

== Software Development Kit (SDK) ==

You can find the [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS SDK at this location].

[[SDK Release Notes|Release Notes]]

[[SDK FAQ|Frequency Asked Questions]]

[[Autodocs:Main|Autodocs]]

[[Fundamental Types]]

== Reference ==

[[Kernel]]

[[Libraries]]

[[Devices]]

[[Resources]]

[[User Interface Style Guide]]

== General Information ==

[[AmigaOS Versions]]

[[Controlling Application Stack]]

[[GUI Programming]]

[[Programming in the Amiga Environment]]

[[Libraries and Devices]]

[[Migration Guide]]

[[Troubleshooting Your Software]]

[[Understanding the alert error numbers]]

[[Release 4 Compatibility]]

[[Writing apps for Xena]]

[[AmigaGuide 101]]

[[Installation Utility]]

[[Optimized Window Refreshing]]

[[Autodoc Style Guide]]

[[Debug Kernel]]

[[AmiDock and Dockies]]

[[Command Line Interface]]

[[DCFS and LNFS Low Level Data Structures]]

UserDoc:Main

2014-09-21T15:26:01Z

Paul Sadlik: /* AmigaOS platform targets */

== Welcome to AmigaOS ==

AmigaOS was born in 1985 and delivered what contemporary personal computer operating systems could only dream of. As the first "multimedia" operating system, it was trivial for AmigaOS computers to display animations while playing music and reading data from disks. Such multimedia and multitasking finesse drew many people to this system. Some of them are famous: [http://www.amigahistory.co.uk/warhol.html Andy Warhol], Sir Arthur C. Clarke, [http://www.polyphoto.com/upchug/AEcastro.html NASA], Hollywood and the TV broadcasting industry, and many others that thought [http://www.youtube.com/watch?v=PWeO5IkCssk only Amiga makes it possible].

Today many people still think AmigaOS has something special that makes it more interesting and rewarding than other systems. This system allows the user to control the computer, not the other way around. It is a system you fully understand that is easier and more flexible to use. In other words, AmigaOS is '''more fun'''.

=== AmigaOS: The flexible operating system ===
AmigaOS is an operating system: a collection of efficient programs written to start the computer, let the user control the computer, and present feedback to the user.

AmigaOS is designed with ease of use and flexibility in mind. To begin with, AmigaOS provides a clear view of your computer, your applications and files. A number of methods are available to let your computer serve you, whether graphically with a mouse, using the "Shell" command line, or by some other means the user prefers.

AmigaOS strives to avoid stupid limitations that can be found on other systems. AmigaOS users can organise their files the way they like. There are few limits on file hierarchy, locations and file names. Drives don't have to be named with a letter or cryptic names (such as C:, or sda1), your files don't have to reside in your "Documents" folder and your hard drives aren't hidden from you. If you're not writing to drives and you want to "shut down", why wait for the OS to allow that? With AmigaOS, just hit the power switch. Done.

An Amiga does not start with pre-installed applications serving some sales conglomerate, marketing organization or their big brother. AmigaOS does not do actions behind the user's back. As unique as it is today, the AmigaOS computer serves the user and not the other way around. With one of the largest proportions of user-programmers around, the trustworthy AmigaOS user-friendly ethic is mirrored in AmigaOS applications.

Since the first versions more than twenty-five years ago, AmigaOS has also been designed to serve efficiently. Optimizing applications and OS code has always been the goal of programmers and developers of this operating system. The result is an operating system and applications that take less space on your hard drives, waste less time loading, consume less memory, require less processing power, and respond more quickly to the user.

And every update of AmigaOS doesn't demand you must buy newer, more powerful hardware. AmigaOS currently runs on twenty year old 200MHz computers or brand new dual core 1,800MHz computers. It's the user's choice how they want to '''enjoy''' AmigaOS.

=== Some AmigaOS features ===
Here are some of the features of AmigaOS that make it easy to control your computer. Some of these concepts were copied by other operating systems which tend to show they are the correct way of doing things.

* '''Small footprint:''' AmigaOS can work with 64 MB of memory. On disk, a default installation only takes around 200 MB. The smaller footprint translates into a more responsive user experience given any hardware.

* '''Straightforward operating system design:''' With a clear layout and easy to understand names (Classes, Libs, Fonts, Prefs, Storage, etc.), you can easily understand what everything in AmigaOS is and what it does for you. Nothing is hidden from the user and the user is not restricted by AmigaOS.

*'''User configurable graphic interface:''' Using the provided "preferences editors," the user can dramatically reconfigure how AmigaOS looks, sounds, runs and responds to every user whim.

* '''File recognition based on file content:''' You can name a file '''whatever you want''', even without an extension. Examples: "my file" or "picture of Jay in Santa Clara". There is no need to add an extension to explain what the file is, like ".txt" or ".jpg". AmigaOS really examines the '''file content''' to recognise what type of file it is.

* '''Logical assignments:''' Easily set and use logical names names for directories located anywhere on your system. For example, "Auto:" can point to your directory "car show pictures" buried on your media drive.

* '''Ram disk concept:''' On AmigaOS there is a special disk called the '''Ram disk''' which represents a part of your computer memory. This area is not fixed. It automatically grows whenever you store files in it. For example, it's a great place to unpack files to install from there, greatly speeding up the installation.

* '''Command line and graphical user interfaces:''' Both the the graphical user interface (GUI) and command line interface (where you type commands into a window with the keyboard) can be used to manage AmigaOS, its programs and files. Both interfaces are intergated with each other so you can easily use command lines from the GUI or open graphical elements from a command line.

*'''ARexx Ports:''' Throughout AmigaOS and third party programs, "ARexx" message ports let one application talk with others so that apps work together to serve the user. AmigaOS also provides the lightweight ARexx and modern Python programming languages that can control AmigaOS and applications with ARexx ports.

* '''Resident Commands:''' Commands can be made resident, i.e., they are kept in memory so that they can be reused with no loading time.

* '''Restart only the operating system:''' if you feel the need to restart the system, you can do so by restarting '''only AmigaOS''' and not the whole computer.

=== AmigaOS platform targets ===

While the original versions of AmigaOS ran on computers of the eighties using Motorola 68k series CPU chips, the current AmigaOS runs on computers using PowerPC processor chips [http://www.amigaos.net/content/72/supported-hardware hardware]. These can be older Amiga computers (also called "Classic Amigas") with PPC "accelerator cards" or new generation Amiga PPC computers.

In this guide, we will concentrate on the current AmigaOS running on the supported hardware:

* [[AmigaOne X1000]] model by [http://www.a-eon.com A-Eon Technology]

* [[AmigaOne 500]], Sam460, Sam440ep and Sam440-flex models by [http://www.acube-systems.com ACube Systems]

* [[Pegasos II]] model by [http://www.bplan-gmbh.de bplan GmbH]

* AmigaOne XE and micro-A1 models by [http://en.wikipedia.org/wiki/Eyetech Eyetech Group Ltd].

* Amiga 4000(T), 3000(T) and 1200 models by Commodore Business Machines (when equipped with PowerPC accelerator cards).

== How does AmigaOS work? - Concepts ==

In this page we will discuss [[UserDoc:How AmigaOS Works|how AmigaOS works]]:

* [[UserDoc:How_AmigaOS_Works#The_most_important_components|The most important components]] (Exec, AmigaDOS, Intuition...)
* [[UserDoc:How_AmigaOS_Works#How_is_my_data_stored.3F|how files and data are stored]]
* [[UserDoc:How_AmigaOS_Works#All_AmigaOS_components|all AmigaOS components are described]]
* [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|how AmigaOS is booted on your Amiga computer]]
* AmigaOS settings programs
* ...

== How to use AmigaOS? ==

AmigaOS is a collection of components that oversee the computer hardware & data and provide the user with easy, understandable tools to manage and use them.

In the following [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS pages]] we will discuss the basic concepts:

* how to use AmigaOS
* what the AmigaOS graphic user interface is composed of
* what interfaces AmigaOS provides, including the [[UserDoc:Workbench|Workbench]], the [[UserDoc:Shell|Shell]] or scripting languages.

From the introduction page, you can continue with more detailed pages on the [[UserDoc:Workbench|Workbench]] and the [[AmigaDOS manual]] . Now let's start with this [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS]].

== Manuals ==

[[UserDoc:AmigaOS File Systems|AmigaOS File Systems]] - AmigaOS File Systems

[[AmigaOS Manual]] - AmigaOS Manual

[[Bars & Pipes Professional]] - MIDI Sequencer

UserDoc:How AmigaOS Works

2014-09-21T15:19:14Z

Paul Sadlik: /* The Workbench */

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory i.e. AmigaOS will not work without them or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.
After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell you need to issue the command '''list''' to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows to store data on partitions in SFS0 and SFS2
* JXFileSystem - allows to create partitions in JXFS
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* Prefs
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:AmigaOS File Systems

2014-09-21T15:10:29Z

Paul Sadlik:

SFS\00 and SFS\02 support other block sizes but only 512 bytes should be used since it is slower with larger blocks. JXFS only supports 512 block size. Recovery tools are located in MediatToolbox in the SYS:System drawer. Always have a backup.

{| class="wikitable"
|+ AmigaOS File System Table
!
! FastFileSystem<br/>(FFS)
! FastFileSystem 2<br/>(FFS2)
! SmartFileSystem<br/>(SFS)
! SmartFileSystem 2<br/>(SFS2)
! JXFS
|-
| Bootable?
| Yes
| Yes
| Yes
| Yes
| No
|-
| DosType
| DOS\03 0x444f5303
| DOS\07 0x444f5307
| SFS\00 0x53465300
| SFS\02 0x53465302
| JXF\04 0x4A584604
|-
| Max. Filename Length
| 30 characters
| 107 characters
| 107 characters
| 107 characters
| 107 characters
|-
| Max. Parition Size
| 2 TB to 128 TB
| 2 TB to 128 TB
| 128 GB
| 1 TB
| 256 TB
|-
| Max. File Size
| 4 GB - 2 Bytes
| 4 GB - 2 Bytes
| 4 GB - 2 Bytes
| 1 TB
| 256 TB
|-
| Supported Block Size
| 512 to 32768
| 512 to 32768
| only 512
| only 512
| only 512
|-
| Comments
| Legacy file system, not recommended for AmigaOS 4.x due to lack of long filename support. Can be used for bootloader partition in AmigaOS 4.x only setup.
| Current file system, bootable, can be used with AmigaOS 4.x, recovery tools available, not as fast as SFS, requires validation if disk error.
| Current file system, bootable, can be used with AmigaOS 4.x, some recovery tools available. Fast, does not require validation if disk error.
| Current file system, bootable, can be used with AmigaOS 4.x. Fast, does not require validation if disk error. No Recovery tools.
| Fastest but not backwards compatible with some 68K legacy software nor software which abuses DOS packets. No recovery tools.
|}

UserDoc:Main

2014-09-21T15:08:03Z

Paul Sadlik: /* AmigaOS platform targets */

== Welcome to AmigaOS ==

AmigaOS was born in 1985 and delivered what contemporary personal computer operating systems could only dream of. As the first "multimedia" operating system, it was trivial for AmigaOS computers to display animations while playing music and reading data from disks. Such multimedia and multitasking finesse drew many people to this system. Some of them are famous: [http://www.amigahistory.co.uk/warhol.html Andy Warhol], Sir Arthur C. Clarke, [http://www.polyphoto.com/upchug/AEcastro.html NASA], Hollywood and the TV broadcasting industry, and many others that thought [http://www.youtube.com/watch?v=PWeO5IkCssk only Amiga makes it possible].

Today many people still think AmigaOS has something special that makes it more interesting and rewarding than other systems. This system allows the user to control the computer, not the other way around. It is a system you fully understand that is easier and more flexible to use. In other words, AmigaOS is '''more fun'''.

=== AmigaOS: The flexible operating system ===
AmigaOS is an operating system: a collection of efficient programs written to start the computer, let the user control the computer, and present feedback to the user.

AmigaOS is designed with ease of use and flexibility in mind. To begin with, AmigaOS provides a clear view of your computer, your applications and files. A number of methods are available to let your computer serve you, whether graphically with a mouse, using the "Shell" command line, or by some other means the user prefers.

AmigaOS strives to avoid stupid limitations that can be found on other systems. AmigaOS users can organise their files the way they like. There are few limits on file hierarchy, locations and file names. Drives don't have to be named with a letter or cryptic names (such as C:, or sda1), your files don't have to reside in your "Documents" folder and your hard drives aren't hidden from you. If you're not writing to drives and you want to "shut down", why wait for the OS to allow that? With AmigaOS, just hit the power switch. Done.

An Amiga does not start with pre-installed applications serving some sales conglomerate, marketing organization or their big brother. AmigaOS does not do actions behind the user's back. As unique as it is today, the AmigaOS computer serves the user and not the other way around. With one of the largest proportions of user-programmers around, the trustworthy AmigaOS user-friendly ethic is mirrored in AmigaOS applications.

Since the first versions more than twenty-five years ago, AmigaOS has also been designed to serve efficiently. Optimizing applications and OS code has always been the goal of programmers and developers of this operating system. The result is an operating system and applications that take less space on your hard drives, waste less time loading, consume less memory, require less processing power, and respond more quickly to the user.

And every update of AmigaOS doesn't demand you must buy newer, more powerful hardware. AmigaOS currently runs on twenty year old 200MHz computers or brand new dual core 1,800MHz computers. It's the user's choice how they want to '''enjoy''' AmigaOS.

=== Some AmigaOS features ===
Here are some of the features of AmigaOS that make it easy to control your computer. Some of these concepts were copied by other operating systems which tend to show they are the correct way of doing things.

* '''Small footprint:''' AmigaOS can work with 64 MB of memory. On disk, a default installation only takes around 200 MB. The smaller footprint translates into a more responsive user experience given any hardware.

* '''Straightforward operating system design:''' With a clear layout and easy to understand names (Classes, Libs, Fonts, Prefs, Storage, etc.), you can easily understand what everything in AmigaOS is and what it does for you. Nothing is hidden from the user and the user is not restricted by AmigaOS.

*'''User configurable graphic interface:''' Using the provided "preferences editors," the user can dramatically reconfigure how AmigaOS looks, sounds, runs and responds to every user whim.

* '''File recognition based on file content:''' You can name a file '''whatever you want''', even without an extension. Examples: "my file" or "picture of Jay in Santa Clara". There is no need to add an extension to explain what the file is, like ".txt" or ".jpg". AmigaOS really examines the '''file content''' to recognise what type of file it is.

* '''Logical assignments:''' Easily set and use logical names names for directories located anywhere on your system. For example, "Auto:" can point to your directory "car show pictures" buried on your media drive.

* '''Ram disk concept:''' On AmigaOS there is a special disk called the '''Ram disk''' which represents a part of your computer memory. This area is not fixed. It automatically grows whenever you store files in it. For example, it's a great place to unpack files to install from there, greatly speeding up the installation.

* '''Command line and graphical user interfaces:''' Both the the graphical user interface (GUI) and command line interface (where you type commands into a window with the keyboard) can be used to manage AmigaOS, its programs and files. Both interfaces are intergated with each other so you can easily use command lines from the GUI or open graphical elements from a command line.

*'''ARexx Ports:''' Throughout AmigaOS and third party programs, "ARexx" message ports let one application talk with others so that apps work together to serve the user. AmigaOS also provides the lightweight ARexx and modern Python programming languages that can control AmigaOS and applications with ARexx ports.

* '''Resident Commands:''' Commands can be made resident, i.e., they are kept in memory so that they can be reused with no loading time.

* '''Restart only the operating system:''' if you feel the need to restart the system, you can do so by restarting '''only AmigaOS''' and not the whole computer.

=== AmigaOS platform targets ===

While the original versions of AmigaOS ran on computers of the eighties using Motorola 68k series CPU chips, the current AmigaOS runs on computers using PowerPC processor chips [http://www.amigaos.net/content/72/supported-hardware hardware]. These can be older Amiga computers (also called "Classic Amigas") with PPC "accelerator cards" or new generation Amiga PPC computers.

In this guide, we will concentrate on the current AmigaOS running on the supported hardware:

[[AmigaOne X1000]] model by [http://www.a-eon.com A-Eon Technology]

[[AmigaOne 500]], Sam460, Sam440ep and Sam440-flex models by [http://www.acube-systems.com ACube Systems]

[[Pegasos II]] model by [http://www.bplan-gmbh.de bplan GmbH]

AmigaOne XE and micro-A1 models by [http://en.wikipedia.org/wiki/Eyetech Eyetech Group Ltd].

Amiga 4000(T), 3000(T) and 1200 models by Commodore Business Machines (when equipped with PowerPC accelerator cards).

== How does AmigaOS work? - Concepts ==

In this page we will discuss [[UserDoc:How AmigaOS Works|how AmigaOS works]]:

* [[UserDoc:How_AmigaOS_Works#The_most_important_components|The most important components]] (Exec, AmigaDOS, Intuition...)
* [[UserDoc:How_AmigaOS_Works#How_is_my_data_stored.3F|how files and data are stored]]
* [[UserDoc:How_AmigaOS_Works#All_AmigaOS_components|all AmigaOS components are described]]
* [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|how AmigaOS is booted on your Amiga computer]]
* AmigaOS settings programs
* ...

== How to use AmigaOS? ==

AmigaOS is a collection of components that oversee the computer hardware & data and provide the user with easy, understandable tools to manage and use them.

In the following [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS pages]] we will discuss the basic concepts:

* how to use AmigaOS
* what the AmigaOS graphic user interface is composed of
* what interfaces AmigaOS provides, including the [[UserDoc:Workbench|Workbench]], the [[UserDoc:Shell|Shell]] or scripting languages.

From the introduction page, you can continue with more detailed pages on the [[UserDoc:Workbench|Workbench]] and the [[AmigaDOS manual]] . Now let's start with this [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS]].

== Manuals ==

[[UserDoc:AmigaOS File Systems|AmigaOS File Systems]] - AmigaOS File Systems

[[AmigaOS Manual]] - AmigaOS Manual

[[Bars & Pipes Professional]] - MIDI Sequencer

AmigaDOS manual

2014-09-21T14:55:10Z

Paul Sadlik: /* AmigaDOS commands */

== AmigaDOS manual ==

=== Introduction ===

Many beginners are rather confused by the differences between the terms "AmigaDOS" and "Shell". Some people think they just use the Shell or they are just using AmigaDOS commands in a shell window.

The AmigaDOS software is contained in files stored on the system partition. They are all binaries, either programs directly usable by the user, or libraries and other sets of functions usable by any program or AmigaDOS itself.

You can think of AmigaDOS as a complete system for operating the computer and its peripherals. In order to talk with AmigaDOS the user will use a shell to type commands and get the results from them.

=== The Shell ===

The Shell is a "command line interface" (CLI) that provides a lot of features to interact with the operating system.
Simply put, it means that you use an "interface" (in this case a shell window) to send commands to the computer which will use this same interface to display results to your commands.

For historical reasons, you will still find references to the CLI in AmigaOS but this is really a shell that is used everywhere in the system.

[[File:Shell.png]]

Now learn the basics and more complex uses of the [[UserDoc:Shell|AmigaOS shell]].

=== AmigaDOS commands ===

For commands and arguments used in the AmigaOS command line ("CLI"), please see the [[AmigaOS Manual: AmigaDOS|AmigaDOS pages]] (currently historic documentation - to be updated).

AmigaDOS manual

2014-09-21T14:53:51Z

Paul Sadlik: /* AmigaDOS commands */

AmigaDOS manual

2014-09-21T14:52:19Z

Paul Sadlik: /* AmigaDOS manual */

== AmigaDOS manual ==

=== Introduction ===

Many beginners are rather confused by the differences between the terms "AmigaDOS" and "Shell". Some people think they just use the Shell or they are just using AmigaDOS commands in a shell window.

The AmigaDOS software is contained in files stored on the system partition. They are all binaries, either programs directly usable by the user, or libraries and other sets of functions usable by any program or AmigaDOS itself.

You can think of AmigaDOS as a complete system for operating the computer and its peripherals. In order to talk with AmigaDOS the user will use a shell to type commands and get the results from them.

=== The Shell ===

The Shell is a "command line interface" (CLI) that provides a lot of features to interact with the operating system.
Simply put, it means that you use an "interface" (in this case a shell window) to send commands to the computer which will use this same interface to display results to your commands.

For historical reasons, you will still find references to the CLI in AmigaOS but this is really a shell that is used everywhere in the system.

[[File:Shell.png]]

Now learn the basics and more complex uses of the [[UserDoc:Shell|AmigaOS shell]].

=== AmigaDOS commands ===

C commands, command line arguments, please see the [[AmigaOS Manual: AmigaDOS|AmigaDOS pages]].

AmiWest 2013 Lesson 4

2014-05-12T03:24:58Z

Paul Sadlik: /* General Issues */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this server out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide, as described below. Both of these can
be configured using Internet Prefs. You can also make this configuration by
manually editing the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation/Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could manually be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can otherwise make this adjustment to Roadshow's server list by manually adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga (at the port number
following the colon - ":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? Webpages? More?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an image file
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can process them and respond to web visitors. To dig deeper you can
search the many sources online or in your local bookstore on HTTP communications
and the formatting of HTML webpages. Of course, you should make sure your
server can optionally send diagnostics output so you know what requests are
being received and how they are responded to.

===Just Webpages?===

There's also no reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that you could write a server for. Or you could
create your own online client and server pair of applications that
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and requests are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server program will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each instance of the internet server handles each incoming request, quickly
relays the necessary information from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this tutorial.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there are RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities - that isn't reflected in the simple examples above.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T03:22:22Z

Paul Sadlik: /* Just Webpages? */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this server out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide, as described below. Both of these can
be configured using Internet Prefs. You can also make this configuration by
manually editing the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation/Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could manually be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can otherwise make this adjustment to Roadshow's server list by manually adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga (at the port number
following the colon - ":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? Webpages? More?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an image file
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can process them and respond to web visitors. To dig deeper you can
search the many sources online or in your local bookstore on HTTP communications
and the formatting of HTML webpages. Of course, you should make sure your
server can optionally send diagnostics output so you know what requests are
being received and how they are responded to.

===Just Webpages?===

There's also no reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that you could write a server for. Or you could
create your own online client and server pair of applications that
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and requests are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server program will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each instance of the internet server handles each incoming request, quickly
relays the necessary information from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this tutorial.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there are RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T03:11:42Z

Paul Sadlik: /* Where to go? Webpages? More? */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this server out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide, as described below. Both of these can
be configured using Internet Prefs. You can also make this configuration by
manually editing the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation/Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could manually be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can otherwise make this adjustment to Roadshow's server list by manually adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga (at the port number
following the colon - ":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? Webpages? More?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an image file
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can process them and respond to web visitors. To dig deeper you can
search the many sources online or in your local bookstore on HTTP communications
and the formatting of HTML webpages. Of course, you should make sure your
server can optionally send diagnostics output so you know what requests are
being received and how they are responded to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T03:09:33Z

Paul Sadlik: /* Where to go? More Webpages? */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this server out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide, as described below. Both of these can
be configured using Internet Prefs. You can also make this configuration by
manually editing the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation/Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could manually be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can otherwise make this adjustment to Roadshow's server list by manually adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga (at the port number
following the colon - ":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? Webpages? More?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an image file
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can process them and respond to web visitors. To dig deeper you can
search the many sources online or in your local bookstore on HTTP communications
and the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T03:06:53Z

Paul Sadlik: /* Let's See Our Server! */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this server out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide, as described below. Both of these can
be configured using Internet Prefs. You can also make this configuration by
manually editing the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation/Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could manually be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can otherwise make this adjustment to Roadshow's server list by manually adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga (at the port number
following the colon - ":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T02:58:38Z

Paul Sadlik: /* Roadshow Configuration */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this server out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide, as described below. Both of these can
be configured using Internet Prefs. You can also make this configuration by
manually editing the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation/Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could manually be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can otherwise make this adjustment to Roadshow's server list by manually adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T02:47:37Z

Paul Sadlik: /* EXAMPLE TWO: IPserver.c */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this server out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T02:30:54Z

Paul Sadlik: /* Respond to the Visitor */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.
''Italic text''

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T00:27:02Z

Paul Sadlik: /* Receive the Request */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.
''Italic text''

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T00:23:14Z

Paul Sadlik: /* Receive the Request */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.
''Italic text''

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T00:15:23Z

Paul Sadlik: /* Ideas */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.
''Italic text''

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-12T00:06:27Z

Paul Sadlik: /* Ideas */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.
''Italic text''

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-11T23:44:42Z

Paul Sadlik: /* Designing Your Network Client */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.
''Italic text''

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-05-11T23:25:38Z

Paul Sadlik: /* An Internet Client */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.
''Italic text''

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-04-13T20:56:15Z

Paul Sadlik: /* General Issues */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implrementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmiWest 2013 Lesson 4

2014-04-13T20:51:24Z

Paul Sadlik: /* Just Webpages? */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implrementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:37:56Z

Paul Sadlik: /* Where to go? More Webpages? */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:28:02Z

Paul Sadlik: /* Let's See Our Server! */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, preforms no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET" tells the server what the browser is looking for.
If you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers make two connections with one of
them looking saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is looking to see if your server has an icon
to send for the displaying on the browser tab. Just like that, anything
written in URL after the machine's name or IP address and the port number
is taken a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:24:54Z

Paul Sadlik: /* Servers */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have your test server Amiga's
IP address or a host name configured on your network. The URL would
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, preforms no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET" tells the server what the browser is looking for.
If you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers make two connections with one of
them looking saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is looking to see if your server has an icon
to send for the displaying on the browser tab. Just like that, anything
written in URL after the machine's name or IP address and the port number
is taken a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:21:20Z

Paul Sadlik: /* Servers */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = <where are server program is>
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have your test server Amiga's
IP address or a host name configured on your network. The URL would
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, preforms no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET" tells the server what the browser is looking for.
If you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers make two connections with one of
them looking saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is looking to see if your server has an icon
to send for the displaying on the browser tab. Just like that, anything
written in URL after the machine's name or IP address and the port number
is taken a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:19:10Z

Paul Sadlik: /* Services */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
type, wait and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = <where are server program is>
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have your test server Amiga's
IP address or a host name configured on your network. The URL would
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, preforms no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET" tells the server what the browser is looking for.
If you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers make two connections with one of
them looking saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is looking to see if your server has an icon
to send for the displaying on the browser tab. Just like that, anything
written in URL after the machine's name or IP address and the port number
is taken a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:17:28Z

Paul Sadlik: /* EXMAPLE TWO: IPserver.c */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
type and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
type, wait and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = <where are server program is>
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have your test server Amiga's
IP address or a host name configured on your network. The URL would
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, preforms no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET" tells the server what the browser is looking for.
If you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers make two connections with one of
them looking saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is looking to see if your server has an icon
to send for the displaying on the browser tab. Just like that, anything
written in URL after the machine's name or IP address and the port number
is taken a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:13:49Z

Paul Sadlik: /* Respond to the Visitor */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
that tells a user this program wasn't meant to be run from the Workbench.
As it stands, this is program is only meant to be used by Roadshow for
serving internet visitors to your Amiga.

But how do we test this all out? First we have to let Roadshow know that
we've created this

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
type and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
type, wait and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = <where are server program is>
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have your test server Amiga's
IP address or a host name configured on your network. The URL would
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, preforms no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET" tells the server what the browser is looking for.
If you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers make two connections with one of
them looking saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is looking to see if your server has an icon
to send for the displaying on the browser tab. Just like that, anything
written in URL after the machine's name or IP address and the port number
is taken a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:10:57Z

Paul Sadlik: /* Respond to the Visitor */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). At then end we "flush"
the output and quit our program. The request was received, our webpage
sent and Roadshow takes care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
that tells a user this program wasn't meant to be run from the Workbench.
As it stands, this is program is only meant to be used by Roadshow for
serving internet visitors to your Amiga.

But how do we test this all out? First we have to let Roadshow know that
we've created this

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
type and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
type, wait and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = <where are server program is>
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have your test server Amiga's
IP address or a host name configured on your network. The URL would
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, preforms no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET" tells the server what the browser is looking for.
If you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers make two connections with one of
them looking saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is looking to see if your server has an icon
to send for the displaying on the browser tab. Just like that, anything
written in URL after the machine's name or IP address and the port number
is taken a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:09:15Z

Paul Sadlik: /* Respond to the Visitor */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use the same "stdin" stream to respond to our
internet visitor.

Anything we output to "stdin" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
doagnostics print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). At then end we "flush"
the output and quit our program. The request was received, our webpage
sent and Roadshow takes care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
that tells a user this program wasn't meant to be run from the Workbench.
As it stands, this is program is only meant to be used by Roadshow for
serving internet visitors to your Amiga.

But how do we test this all out? First we have to let Roadshow know that
we've created this

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
type and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
type, wait and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = <where are server program is>
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have your test server Amiga's
IP address or a host name configured on your network. The URL would
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, preforms no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET" tells the server what the browser is looking for.
If you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers make two connections with one of
them looking saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is looking to see if your server has an icon
to send for the displaying on the browser tab. Just like that, anything
written in URL after the machine's name or IP address and the port number
is taken a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.

AmiWest 2013 Lesson 4

2014-04-13T20:07:22Z

Paul Sadlik: /* Receive the Request */

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use the same "stdin" stream to respond to our
internet visitor.

Anything we output to "stdin" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
doagnostics print outs, since a simple "printf" would have gone to
our web visitor.

Instead, we create a loop that feeds a predefined series of lines
for a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). At then end we "flush"
the output and quit our program. The request was received, our webpage
sent and Roadshow takes care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE WIDTH=90%><TR><TD><B><H1>WELCOME</H1></B><BR></TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3><P><P><FONT COLOR=\"white\"><B>AmigaOS IPserver example</B></FONT></TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
"<BR><TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4><B>And so it begins...</B></TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
that tells a user this program wasn't meant to be run from the Workbench.
As it stands, this is program is only meant to be used by Roadshow for
serving internet visitors to your Amiga.

But how do we test this all out? First we have to let Roadshow know that
we've created this

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
type and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
type, wait and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = <where are server program is>
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have your test server Amiga's
IP address or a host name configured on your network. The URL would
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, preforms no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET" tells the server what the browser is looking for.
If you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers make two connections with one of
them looking saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is looking to see if your server has an icon
to send for the displaying on the browser tab. Just like that, anything
written in URL after the machine's name or IP address and the port number
is taken a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server functionality.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, there
are basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or full file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to do
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains running
while each of internet server instance handles an incoming request and
quits.

Naturally, at some point use requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server.

Furthermore, there are whole areas of study and technology involved
with the handling of network user load that should be applied to any
serious server system.

====Protocols and Compatibility====

As one develops a more complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should considerin developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, there's no automatic way to know
the next transaction your server receives is that logged in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a servers should avoid making
assumptions about the state of the connection and interaction with a
visitor whenever possible or provide explicit means for addressing such
things.