AMIGIFT Documentation

Table of contents

window
Quick Links: Configuring GiFTMui, giftd, FastTrack, OpenFT, Gnutella, Ares · Application Menu · Search · Advanced Search · Results Listview · Transfers · Tooltypes · Register
        Last Updated: 12th May 2009  

 

top toc prev next

Introduction

AMIGIFT is a p2p file sharing application for the Amiga® platform and AmigaOS® compatible systems (AmigaOS v3.x, AmigaOS v4.x (PPC), MorphOS, ...), Unlike many others applications, like Kazaa or Limewire, it connects to several peer-to-peer networks at a time and it contains no spyware and no adware. Its based on a derived work from the GNU's giFT project originally written for the Linux platform.

It uses various software components to consolidate the system, The central application, giftd, is a daemon which uses a plugin-based architecture capable of using multiple networks simultaneously through GiFTMui: the user interface.

AMIGIFT was originally created around the end of the year 2003, at that time it used the ixemul.library which a unix-kernel's based shared library for AmigaOS® that makes porting stuff from the unix world quickly and easy, with the disadvantage that programs works somewhat slower.   Todays, as of version 2.x, the whole core have been greatly improved being ported to be a 100% AmigaOS-native application, that includes conversion of Linux's .so library files to Amiga's .library and plugins on the same way, so that they are no longer linked with the daemon binary making updating each component lots easy and fast at less, creation/implementation of new p2p networks should be now just at your hand.   As you can think there are several other areas which had to be adapted/rewritten because the available C link library(s) for Amiga (e.g: libnix or clib2) wasn't enough for the job, we are talking for example about to implement - or better say, replace - the infamous fork() function. In the other hand, we have finally opted on using our own made C link library, but for debug purposes mainly though, there shouldn't be currently any reason why we wouldn't use clib2 which the best C link library we - amiga users, and developers - can use atm.

About the Graphical User Interface (aka frontend) available for AMIGIFT, It have been created from scratch using MUI (Magic User Interface).   To strict users out there we have to admit it was a big programming lesson.. since at time of creation (at 2003, as above mentioned) there was nearly (or full) zero knowledge about coding MUI, or almost of C/C++ in general, to be honest!   Todays, as of version 2.0 build #16x, the whole code (~50000 lines, ~2.0MB) have been revised and re-structured, being the 80% or so optimized and/or rewritten, e.g: the application is now created using MUI's Custom Classes (OOP) for everything rather than "static objects".   Sure the gui design has some objections from some of you as it's still being developed under an AGA system and therefore could look a bit weird under RTG systems, sorry about that, but at least what we have always in mind is functionality rather than design, (even when unfortunately looks like when a program hasn't a good esthetic design all the rest is forgotten, may just a personal feel...)

As a final introduction step, this documentation assumes you have (at least) a basic knowledge about peer-to-peer file sharing, if isn't your case there are several places on the net where you could find information about, e.g.: Google or the Wikipedia


 

top toc prev next

Core Components

Several users seems confused about all the names of the programs/components AMIGIFT uses, well, here we will describe all of them.   First of all, "AMIGIFT" is the term who name gives to the whole package, nothing more. Each of the components ported from the Linux side have they original name, and valid therefore anywhere in the world.

Before going to explain each of the components, a brief history about the project(s):   The giFT project was born around the year 2001, at that time and as an immature project it was provided with a CGI-Interface to be run from Apache, the project seems to started going well but for some reasons it was drop some time later, the project was then taken (at the year 2003) by Josh Guilfoyle who rewrote lots of code implementing a linux-based plugins system and designing the OpenFT network, thanks to his excellent work the AMIGIFT project was born some weeks later.   The names being used, and the way we write them:   The name "giFT" stand for "GNU Internet File Transfer", it was written on that way (lower -> upper case) because there is another GNU package called "GIFT" which means "GNU Image Finding Tool", both packages was released around the same time, and nothing of the authors noticed the coincidence once both of them was already released.   Hence, the package for AmigaOS should be written "AmigiFT" to be quite correct, however I personally like to write all uppercase or lowercase (eg: amigift or AMIGIFT), (Also, we have noticed some news sites keep writing "AmiGIFT" when indeed it is not the Amiga version of the GNU's Image Finding Tool), All this on, when the port to Amiga goes "AMIGIFT" we adopted it as an acronym to "Amiga Internet File Transfer" following the giFT way, and then the Amiga's frontend spelled "GiFTMui" which stand for "Magick User Interface for giFT", well, we are now ready to explain each of the components AMIGIFT uses:

Main components

giftd

This is the central component for the AMIGIFT system. giftd is responsible for loading and executing network plugins, handling the remote interface protocol, managing searches, file exchanges, and other critical activities that exist above the network protocols themselves. In other words, giftd is the AMIGIFT work horse.

gift.library

Support and utility library for giftd and network plugins. This library is essentially a grab bag of tools, data structures, and common functionality needed by, and found in, most large C projects. While it is only critical for giftd, it can be a very useful tool to aid in developing giFT-related utilities. The source is heavily documented in the doxygen tool format.

giftproto.library

Library which designs the API to networks plugins, A great majority of the interaction between the daemon and plugins is defined by a single interface in the source code header file protocol.h, which is naturally heavily documented internally.

giftmeta.library

This library implements utility functions to extract meta data info from some common streams, like avi, mpeg, ogg,etc. it is used mainly when a hashing of your shared files and/or completed downloads is performed. Extracted information are width, height, fps, bitrate, etc which later are sent through search requests.

amigift.library

This library implements helpful utility functions to AmigaOS-only clients, this isn't a ported library but created from scratch to fit our needs, this library is still being heavily developed with new functions being added, or changed/optimized, each time. Everything is subject to change, but keeping backward compatibility where possible, hence you're encourage to use the very latest version all the time.

GiFTMui

It is the user interface or frontend, it has been created using MUI (Magic User Interface), a Reaction-based frontend may come later as we started writing it but stopped due to lack of motivation...



Known Network Plugins

OpenFT.PlugIn   officially supported

A network designed exclusively around the framework, loosely based on the main design principles of the FastTrack network. OpenFT offers pretty much all of the major features you'd expect to see from the larger networks (Gnutella, FastTrack, eDonkey, etc), despite maintaining a relatively small and manageable user base. This network plugin was built and maintained by the core giFT developers, and is considered an official component of the giFT project.

Gnutella.PlugIn   officially supported

Gnutella1 plugin officially distributed by the giFT project.

FastTrack.PlugIn   officially supported

Implements the hugely popular FastTrack network used by KaZaA (and formerly Morpheus and Grokster). Please note that this plugin was produced independent of the KaZaA source code and does not necessarily behave the same. In other words, you're accessing the same network that KaZaA is, but in a slightly different way.

Ares.PlugIn   officially supported

A plugin that connects to the Ares network, another FastTrack-like network.

OpenNap.PlugIn

Mostly defunct plugin to access opennap servers (via the Napster protocol).

SoulSeek.PlugIn

Totally broken mess that needs to be rewritten entirely to be of any use...

Aminet.PlugIn

A plugin which connects to the WWW Aminet Server(s), being able to search and download from the p2p frontend, with the new Aminet WWW Interface this plugin has become almost useless...

DirectConnect.PlugIn

far from finished DC Network plugin, currently it supports connecting to one hub, downloading and uploading files and file-lists (user browsing). As giftd doesn't have any support for chatting through the p2p networks, this plugin opens another port where the chat-messages are forwarded using a simple protocol. There are also several hacks which force giftd to handle files without a hash (still common on DC) properly.

Mute.PlugIn

A plugin to connect to the MUTE network. This plugin was created some years ago but never finished, it even wasn't never tried to be ported to the AMIGIFT project.

Turtle.PlugIn

a p2p network architecture for safe sharing of sensitive data (...) As for Mute, it was created some years ago but never finished, it even wasn't never tried to be ported to the AMIGIFT project.

BitTorrent.PlugIn   officially supported

A plugin to download .torrent files which currently being developed, very slow though..

Status: We have started working on this plugin being the skeleton (well, and beyond it!) quite ready, but stopped its development due the complexity of the integration/implementation of it into the giFT core altogether with our low free time during the past months. Hence, we have decided the fully integration of this plugin will directly depend on the number of registrations reached with the 2.0 release.. Sorry if that does not sound friendly.. but sure most of you understand it, specially those of you who know how BT works internally.. (at least, the GUI part is ready). Please, help us help you! :)




 

top toc prev next

Requirements

AmigaOS Version 3.0 or higher (info)

At time of this write, AmigaOS 4.0 (PPC) and MorphOS are supported under its native m68k emulation. (Petunia and Trance respectively, under os4 you have to have installed the July-2007's update or amigift will not work properly!)

Users of Windøws, GNU-Linux or Mac systems could even try AMIGIFT by using an Amiga Emulator such as UAE (or any of its variants), for Windøws users there is available WinUAE but you'll still need a copy of the AmigaOS and ROMs, you can purchase Amiga Forever which includes everything you need to have a full working Amiga Operating System. - There is also AmiKit which a recopilation of freeware/shareware programs for AmigaOS running under Windøws using the WinUAE core (but with neither OS nor ROMs), you could also purchase Amiga Forever from the AmiKit website to support both projects for the same (cheap!) price.

68020 or better CPU.

Even if it should work under a 68020 CPU, it is highly recommended to use a better CPU (e.g.: 68060), else you could hardly use all of the available compoments.

About 32MB of FREE RAM.

Note that the memory required directly depends on the number of network plugins you use, for a single plugin may the memory required is about 6MB or so only (that also depends on how that particular plugin works internally)

8MB of free Hard Disk space

Minimal installation requires about 8MB of free disk space, while if you intent to save downloaded files at the same installation path (which recommended) thousand of MBs may are needed.

AmiTCP (or compatible) TCP/IP Stack.

Be aware that AMIGIFT, like any other p2p filesharing program on other systems, needs high TCP resources due the high amount of simultaneous connections it may needs to manage, by that reason a good TCP/IP Stack which uses/requires a few system resources is highly recommended (e.g: we recommended Genesis under AmigaOS 3)

A Fast FileSystem which supports long-filenames

Here we recommend SFS (Smart File System) without any doubt.

infoNote: such a file system is really only needed to the incoming and completed folders, where downloads are saved (the incoming folder is used to keep currently being downloaded files, and once finished they are moved to the completed folder), that means you could have the normal installation files at any type of partition (e.g: FFS) but such folders (both) at a SFS partition to properly save downloads with long filenames.   Whatever you decide be sure the completed and incoming folders are on the same partition, else moving a downloaded file from incoming to completed could take a long and unneeded time!

MUI (Magick User Interface) Version 3.8 or higher

MUI is the AmigaOS's state-of-the-art OOP system for creating graphical user interfaces for programs, nothing is better being so easy to create GUIs with such a high-end result </propaganda> :-)

The following MUI's Public Custom Classes are required/used:

· BetterBalance.mcc

subclass of Balance class which allows easily save and load all balance settings of a GUI.

Author: Maik Schreiber website, download mirror .readme

· BetterString.mcc

BetterString is a stringgadget replacement, using it should eliminate the problems with the original BOOPSI stringclass.

Author: Allan Odgaard. website, download mirror .readme

· Busy.mcc

Custom Class to be displayed when the appication is busy doing things...

Author: Klaus Melchior website, download mirror .readme

· BWin.mcc   (It's optional)

Window.mui subclass which offers a very simple bordeless window with a drag bar and a size gadget.

Author: Alfonso Ranieri website, download mirror .readme
infoNote: It requires popupmenu.library

· GIFAnim.mcc   (It's optional)

Area.mui subclass which can be used to show gif pictures and gif animations. It uses an async decoder to parse the gif file.

Author: Alfonso Ranieri website, download mirror .readme
infoNote: It requires asyncio.library

· GuiGfx.mcc   (It's optional)

Area.mui subclass used to display image files in any format datatypes.library understands, guigfx.library image objects, bitmaps and Intuition images. It supports color depths up to 24bit, transparency channels/masks and various scaling modes including aspect correction.

Author: Matthias Bethke website, download mirror .readme
infoNote: It requires guigfx.library and render.library

· Lamp.mcc

Lamp.mcc offers a little lamp which can be used for various purposes. It enhances the programmer's abilities to give more informative feedback to the user and thus just adds another level of communication in your programs!

Author: Maik Schreiber website, download mirror .readme

· NList.mcc

This is a MUI custom class package containing replacements for List/Listtree/Listview/Floattext/Bitmap MUI default class.

Author: NList Open Source Team website, download mirror .readme

· TearOff.mcc   (It's optional)

classe which allow the MUI application to create special groups called TearOffPanels. They can be freely arranged by the user, dragged outside the window or hidden.

Author: Szymon Ulatowski website, download mirror .readme

· TextInput.mcc

Advanced String.mui replacement with lots of extra features, used as well as a combined single/multi line editor gadget.

Author: Oliver Wagner website, download mirror .readme

· ToolBar.mcc

The name almost says it all. It is a MUI custom class that allows easy (very easy) implementation of toolbars in all kinds of MUI programs. It features a multitude of different settings and the majority of these are configurable for the user via the MUI preferences system.

Author: Benny Kjaer Nielsen website, download mirror .readme

· Urltext.mcc

Urltext.mcc is a subclass of Area.mui and offers a very simple text that acts like an active url, as a html link in a browser.

Author: Alfonso Ranieri. website, download mirror .readme

Shared Libraries

· xml2.library   (It's optional)

This library is used by the Gnutella plugin to decode meta-data tags returned with the search results, it isn't really required and neither recommended if you don't really need it, better avoid using it...

· bzlib.library

bzlib.library is used to decompress the build-in (bzip2-compressed) configuration files, therefore you have to have it installed or you'll be unable to save the core components configs to disk. (It's included with the distribution)

· asyncio.library

From AMIGIFT Version 2.0, asyncio.library is used by the daemon to manage downloads on a asynchronous way.   Download it from here.

· openurl.library

It's used from programs to open certain URLs on your default browser, as you sure know.   Download it from here.

Other requirements

· WAVE Sound Datatype (or compatible)

Several event notifications are handled altogether with a sound, on previous versions there we have mixed sound formats, being IFF/8svx and WAVe, todays all of them are in WAVe format (regardless of the file extension)

You can obtain such a WAVe datatype from Aminet, We recommend the wav.datatype V41.10 by Stephan Rupprecht available here

Users of the MorphOS system are encouraged to use Reggae: The streaming media library for MorphOS, AMIGIFT has native support for it by using the 68k wrapper library included on the package.

infoNOTE: If Reggae isn't found under your MOS system, an additional sub-process to handle sounds will be created due some issues we have noticed by launching sounds on the normal-way from the main task.

info Note: All the sound events are optional, you can disable all of them from the preferences window.

· GPatch by Ralf Gruner

GPatch allow us to distribute e.g. ~90KB files rather than 1MB binaries, It is available here, there are also the GPatch program available for Windøws and Linux.

· Players to watch downloaded files.

A feature AMIGIFT still lacks is an embed player to just downloaded files, well... thats at least at time of this write, as we want to implement it somehow, unfortunately (for OS3 users) this looks like it should be a feature for PPC-systems.., Reggae looks like a good candidate to integrate it on that way when it's ready...

For now we'll give you a list of external players suitable to use from the frontend, remember multiview is of use for most files while you has datatypes installed for the specific files, but anyhow we'll give you that list:

  • Visage: Picture viewer for OS 3.0+ (AGA/RTG), by Magnus Holmgren
  • RIVA: Fastest 68k MPEG Player for AGA/RTG, by Stephen Fellner
  • MooVid: MOV and AVI Movie Player, by László Török
  • MPEGA: MPEG Audio decoder library, by Stephane Tavenard
  • SongPlayer: Powerful audio player for IFF, AIFF, WAV, AU, MP2, MP3, MP3PRO, and CDDA file formats, by Stephane Tavenard
  • APDF: PDF doc. viewer, by Derek B. Noonburg and Emmanuel Lesueur
  • MPlayer-os4: Universal audio/video player, AmigaOS 4.0 Version ported by Andrea Palmatè
  • MPlayer-mos: Universal audio/video player, MorphOS Version ported by Nicolas Det


info Note: Players are optional, you can disable all of them from the preferences window.


 

top toc prev next

General Usage


GiFTMui's main window:
Click to enlarge

On this section we'll try to explain in detail the meaning of the hundred of buttons, gadgets, options and internal features available into AMIGIFT, starting with GiFTMui, the Graphical User Interface, with help from some screenshots for a better and quick understanding, focusing as well in the daemon part about command-line options and other aspects which should need mention from this documentation, without forgoting giftd, the daemon, has its own website located here, where you should take a look into if you want a more in depth information about it.

Once you install/extract the package, with the components required and network plugins you wish to use, including 3rd part resources needed, what you'll have to do is to double-click the GiFTMui.info icon to launch the program, then you'll see the following splash-window to the startup process:


splashwindow

On that window you'll see the release name (if it's public or beta), followed by the compilation date and time, next to that is a gauge to the current startup progress, being the screen-title showing as well the progress as percent.

In a few seconds the startup step must be complete, and you'll be presented with the main window.

infoNote: You'll may notice from version 2.0 the startup process is somewhat slower... thats because we use private custom classes for everything MUI related, and almost 40 of them have to be created...

 

If you launch GiFTMui for the first time, you'll see a welcome-window as the follow captured, on that window we give you some additional info which you must read and remember.


welcome window

 

Well, we'll start right now explaining in detail everything:

  hand [ GENERAL USAGE ] Main Window / ToolBar  


main window toolbar

· Thats the main window toolbar, the buttons are as follow: (from left to right)

infoNote: those ghosted buttons are due we grab the screenshot without being connected to the daemon, once connected they are in normal state and the 'Connect' button ghosted.

- Connect

This button connects you to the daemon.   If the daemon isn't running already, and you are using the launch on startup option, it will be automatically launched. Some daemon's command-line/process options can be configured from the preferences which will be used by GiFTMui at time of using SystemTags()

- Disconnect

This buttons closes the connection established with the daemon, Note it only disconnects you from the daemon, which is keep running in the background.

- Search

Use this button to start a search once you adjusted the search criteria from the search panel.   Multiple search requests at the same time are possible if you set the multi-lists switch on (registered users only). Pressing the Enter key over the search string has the same effect than clicking this button.

- Stop

This button stops the current search request.   On previous versions/builds when you click it all further result's additions are rejected ensuring you'll have upto search box's max-results as maximum - this no longer works in this way because there is no real need to ignore further results since the daemon will continue sending them to us until it receives the stop request from the socket connection and process it. note this action is launched in real-time whatever you use sockopt's send queue or no, and once the request has been sent the button gets ghosted.

- Download

This button request the daemon to start downloading the selected entry from the list of results, thats the same as double-click a entry from the results-list. Multiple download requests at once are perfectly possible.

infoNote: There are some options at the preferences about certain actions to be performed at time of downloading (and with each selected download in case of multiple requests)

- Statistics

This button opens a window for network statistics, you'll see number of users, files and bytes for each network, as well the number of downloads/uploads from/to a particular network which GiFTMui itself track internally.

infoNote: Recent Ares versions don't report real stats, it's not a bug, at least not on our part, we just set what the supernode tells us, if it's an old supernode then i'll work, if it's not...it won't...

- Shares

This button shows your list of shares (shared files). If multi-lists are enabled it will show your shares on a new list.

- Transfers Window

This button opens the window where transfers can be watched. Explained below.

- Preferences Window

This button opens the Preferences Window, where you can define the settings for everything. (well, almost everything, there are some options managed by tooltypes and environment variables). Explained below.

- AMIGIFT Anim

Here we have a little amigift anim loaded via GIFAnim.mcc from AMIGIFT:Images/amigift.gif. If you do not have GIFAnim.mcc installed on your system that will be just a noop (hidden) object, not causing any failure at all. You could also replace that GIF anim for anything else you'll like to see here, or rename the image filename if you do not want that anim to be shown.

- Network's Status Lamps

As a last toolbar member we have here a group of status lamps (created with Lamp.mcc, which is therefore required). Since AMIGIFT 2.0 build #156 those lamps are dinamicaly created based on the network plugins currently installed rather than for known plugins.

Follow are the default color specification, the name between quotes is the color name as it appears on the MUI Settings for Lamp.mcc (Its mcp) which you can change to something else:

green "Ok" the plugin is active and connected to the network.
yellow "Processing" the plugin is active but not connected to the network.
black "Off" the plugin is installed but it's neither connected nor active.

Those lamps acts as buttons as well, it serves to enable searching at certain networks only in the same way of using the advanced search panel's protocol checkmarks, when some lamp is pressed the corresponding checkmark will be activated as well, and the lamp will blink using the color "Looking Up"

infoNote: BLACK status lamp at startup means we have not received a stats report from the daemon yet, same if we have reloaded the daemon.





  hand [ GENERAL USAGE ] Main Window / Search Panel  

top

search panel

This is the normal search box, just below of the toolbar, follow explained from left to right:
- Search String

Here you put the string you want to look for, normal searches would be a single word... but you can use any number of words without problems (while the network plugin where to send the search allow it), when you use more than one word is the destination network plugin (supernode) the responsible of handling it on a "human readable" way... unfortunately this does not seems to happen most of the times... to work against this behavior GiFTMui implements some filters to get results e.g. on ordered words (as you typed it).   This object hasn't notification to the return key and therefore you'll need to click on the Search Button to start the search.

The object is created using a String.mui subclass with history/cache facility, when a new search request is sent the string you typed is stored on a private cache, you can access such cache by using the RMB (right mouse button) over the string object and a context-menu with the cached entrys will be shown. If you want the cache saved upon exit you'll have to active the 'save on exit' switch available from the same context menu.

Attached to the string object there is a button as you can see (MUI's "tape down" image), this is here to expand/replace the standard search panel to the advanced search panel mode, where you can finetune the searches (explained below).

- Realm

Here you can define what type of results you want to be returned, this could be everything meaning any type of files, audio, video, images, documents, or software. There are options as well to found files based on its hash, or to browse a single user shares (if the protocol support it).

- Max (Maximum number of results)

How many results do you want as maximum for your search requests, read the notes given to the toolbar's stop button for additional info.

infoNote: The value set here is valid and used as well while the advanced search panel is being used.

- Paths

Activating this switch causes the paths to the files in the results to be shown, this is only usefull if the network/supernode who give us the results uses pathed files.





  hand [ GENERAL USAGE ] Main Window / Info bar  


info bar

Thats the main window's informational string, (no connection to the internet at time of the capture causes the message shown here), where periodic actions are shown, most of them are inserted on the debug window as well (accessible from the program menu).

That info-string is really a Gauge.mui object, we'll use the gauge feature as a progress indicator for the number of results currently received against the maximum value defined defined above

Attached to the info string are two more objects, those are used as counter for the number of selected entrys (to download) and the number of sources for the active entry, respectively.





  hand [ GENERAL USAGE ] Main Window / Results Listview  

top

results nlistview

This is the list of results.   What we see here is three simultaneous searches, on the list title are the search string as you typed it, followed by the current number of results found and then the formated size of all results.   The list title will be highlighted when new results are found for a list which isn't the active one, and changed to bold when the search finishes.

Currently the list of results are formed by 27 columns to give accurate info about the result, Note there isn't returned always enough info to full fill all of the columns, that depends on which software used the peer who gave you the result(s) and the file type/format. A summary of all of the columns contents can be seen by selecting an entry and keeping the mouse quiet over the list, a bubble-help will popup with the info.

The currently being used columns are the follow:   availability, file, size, user, node, url, mime, hash, bitrate, frequency, duration, audioformat, audiofreq, audiobitrate, videoformat, resolution, fps, width, height, format, comment, title, album, track, artist, year. - You can disable as many as you would want using the context-menu over the NList-title, as for adjust the width or the order.

  In Detail:
Column Description
   av  Availability of the file:

* RED: 0 slots available to download at this time.
* YELLOW: 1 slot available, we may download it but probably too slow.
* SHADOWGREEN: 2-6 slots available, we should be able to download it.
* GREEN: all slots available, the peer isn't uploading to other users atm.

infoNote: When the lamp isn't GREEN means the peer is uploading to other users which could make our download to be [somewhat] slow. Consider as well the inet connection that peer have, obviously isn't the same uploading to 4 users/peers with a 1MB-DSL than with a 20MB-DSL connection (Well, if you live at Spain, or want to download from Spanish people, note it's the same...), above all this it could be as well the peer who owns the file has limited its bandwidth usage and/or other inet programs he may have running are limiting the bandwidth as well, as a result your download speed could be ridiculous. just remember those points and do not blame the amigift authors by low download speeds as some of you did, it is something we have not on our hands.   - Note also there are sometimes where we may be able to download files with RED lamp, this only means from the time passed from the supernode to give us that result and we try to download it some slot goes free, it may worth a try to try to download such result if there aren't other good alternatives.
   File  Filename (may contains a path, whatever it's saved without a path)
   MIME  MIME type of the file
   User  User supplying the file
   Node  (super)node this user is connected to
   Bitrate  Bitrate for audio or video files (On videos it's the general bitrate)
   Frequency  Frequency for audio or video files (On videos it's the general frequency)
   Duration  Running time of audio/video files
   AudioFormat  For video files, this contains the format of the audio stream
   AudioFreq  For video files, this contains the frequency of the audio stream
   Bps  bits per second
   Audiobitrate  For video files, this contains the bitrate of the audio stream
   VideoFormat  Which Codec used on video files (AVI, MPEG, etc)
   Resolution  Resolution of video files
   Fps  Frames per second
   Width  Width of images
   Height  Height of images
   Format  Image format
   Comment  Comment supported from some formats (eg MP3)
   Title  Song title
   Album  Album the song was taken from
   Track  Track number of a song on the album
   Artist  Performer of a song
   Year  Release time of the song/album
   Network  Network that the file was found on
   Hash  ASCII Representation of the file's CheckSum (MD5, SHA1, etc)


When AMIGIFT 0.1 was created, we checked all those are the data returned as meta-tags from the various networks, Todays we have noticed new tags are being used but to avoid adding even more columns all those unrecognized tags will be appended to the Comment column.

Build in the list of results are available a context-menu with certain actions we'll explain now, some of the options are actions to be performed over a selected entry, for those click RMB over the desired file.
- Use multi-lists

Toggle the multi-list option that determines whether to open a new list upon each search or not.

regwarn(for registered users only)

- Format Bytes

Toggle the Convert Sizes option that allows you to convert file sizes from bytes to something better readable (eg: 1234567 -> 1.23MB). Here we use 64-bit functions which allow us to convert upto one exabyte (1152921504606846976 Bytes) what does not mean we may be able to download something higher than 2GB ...

- Add new (page) list

Opens a new results listview.

- Remove current list

Closes the current list when the Multi-Lists option is active. If the current list is the only one, nothing will happen.

- Clear current list

Removes all contents from the current list.

- Load results from disk

Loads a previously saved results list from disk into the listview.

- Save results to disk

Saves the current search results to disk. Only the columns required to download or to create a GiFTMui's cache entry are saved, the availability field will obviously be inaccurate if you load the list some day(s) later (or even some minutes/hours later)

- Downloading »

- Add all sources

Scans the search results for identical files and adds them as sources. You can define how many sources to add at once from the preferences window.

- Check if exists locally

Checks if the desired file has already been downloaded before. At which paths to check are defined on the downcheck settings.



- Select »

- All

Select all entrys on the current list.

- None

Deselect all entrys on the current list.

- Toggle

Toggles the status of all items in the current list. Selected entrys becomes deselected and vice versa.

- By Pattern

Opens a tiny window allowing you to specify a name pattern for files to be selected and a cycle gadget that determines where to search for this pattern. Valid options are File (name), MIME (type), User, Node, Comment, Title, Album and Artist. Clicking the "Go!" button perform the selection inserting the matches on a new list. This pattern allows to use regular expressions.

- Max Sources

Search the list for the entry with the highest number of sources, and auto-select such entry.



- Browse 'user' shares list

Request the shares list of the user under the active entry. This option is only available for networks which support user browsing (eg: OpenFT)

- BAN xx.xx.xx.xx

This option is available for FastTrack and Gnutella only. It will add the shown IP to the banlist (for FastTrack) or hosttiles.txt (Gnutella) files which contains lists of banned IPs (by spam, fakes, etc). You can ban a single user or a whole (super)node.

- Where is this file from?

This is an external service provided by www.sharemonkey.com where the AMIGIFT project is affiliated to. When you use it, we'll use openurl.library to redirect you to the ShareMonkey website where you could found addtional info about the selected entry on the results listview, you'll find several places where to legally buy [online] the file or the album where it is.
infoNote: Please support AMIGIFT by clicking on it as many times as you can. (and buy something as it's the way we are rewarded) :-)





  hand [ GENERAL USAGE ] Main Window / Advanced Search Panel  

top
advanced search panel
Thats the advanced search panel which hidden by default and opened clicking the tape down image from the normal search panel.

Clicking on the tape up image (read 'switch panel') will exchanged the panel to the normal one.

Search String and Search Realm was already explained before, Exclude is a string (allowing unix wildcars, teorically..) which will be used to hide certain results from the search, of course the network/supernode where we have sent the search request must accept exclude tokens or giving something here will be a no-op.

Protocol contains a list of currently installed network plugins where we are able to send search requests to certain networks only, or individually. It's default to All Networks.

Filters is a in-depth way of giving more accurate results with the cost of more cpu usage with each request, on previous builds the filters was always "on" and we was checking if the options contains something useable, as it looked like it used here some unneeded cpu (GetAttr() usage on each object for each inserted result) we decided to disable the filters completely by default, and therefore you'll need to Enable it prior to use

Following we are going to explain all of the Filters options:
- Pattern

This is either an AmigaOS or REGEXP (Regular Expression) pattern, which will be compared against received results and only filenames matching will be inserted on the results list. The first character of the string must be colon to use a REGEXP pattern (eg: ":/.*?(mp3|wav)$/i"), if you are new to regexp take a look here, or here.

Regular Expressions support is provided by the PCRE library:
PCRE is a library of functions to support regular expressions whose syntax
and semantics are as close as possible to those of the Perl 5 language.

                       Written by Philip Hazel
           Copyright (c) 1997-2008 University of Cambridge


- Availability

Here you are able to define the minimum availability a file must have to be added to the results list.

meaning of the values was previously explained

- Max FileSize

How many bytes for a file are valid to be inserted on the results list. Files with higher bytes will be just ignored.

- Min FileSize

This is just the opposite to Max FileSize, files with lower bytes than the value entered here will be ignored. You can specify a range of bytes using both fields altogether.

- Match

When you use more than a single word in the search string, most supernodes of certain networks ignores the order or number of words you typed and just returns results matching any word, this is indeed a too annoying behavior at time of looking for phrases with common words - by that reason this filter was created, here you can specify some criterion of how results should be returned. We'll only perform the check on the returned filename field.

The contents of the cycle object are now explained:

- Disabled

Ignores the filter.

- any word

Return results matching any word.

- all words

Only return results which contains all of the words in no particular order.

- all order

Only return results which contains all of the words ordered, just as you typed them.







  hand [ GENERAL USAGE ] Main Window / Downloads Listview  


1 mw_dtrack1
arrowdownfilled
2 mw_dtrack2
arrowdownfilled
3 mw_dtrack3

Just below the main window's results listview you have a 6-pixels height gauge-button as shown on the image 1, When you click it a downloads list will appear as shown on image 2, It's disabled by default and you need to activate it by using its context-menu under the option "enable this (cloned) list", thats a NList's cloned-list meaning the list do not handles anything in his own but inherit the entrys of the main downloads list form the transfers window. Once activated it will look as shown on the image 3, you have quite the same functionality as the main downloads list by using its context-menu options. Shown on image 3 are the gauge activated as well, which also is disabled by default and activated from its context-menu option, This gauge serves as a global counter for all the active downloads, measuring download rate and time all of them will took to complete. Also, there is a Balance object above that cloned list which allows you to resize that list against the results listview. - Note both functionalities could increment the cpu usage substantialy!

regwarnThis feature is available for registered users only





  hand [ GENERAL USAGE ] GiFTMui Application Menu  

top

GiFTMui Menu

Thats the little GiFTMui menu currently in use, there aren't available too many options but just the helpful ones ;)

On this section we'll explain in detail all of the available menu options.

- Project

- About

Opens a window that contains information about the version/build you're using, the author(s) and 3rd part resources used as acknowledgments, and something else related to the current amigift development, including support links.

- About MUI

Opens a window that contains information about the MUI toolkit including version and contact details of MUI itself as well as installed MUI custom classes and their authors.

Those of you who still without a MUI keyfile can start the registration procedure by clicking the central "Register" button. (Or follow This Link)



- Register

This application menu item opens a window that informs about the advantages of obtaining an AMIGIFT KeyFile.

The registration fee can be paid using PayPal. (for other payment methods please ask us), a click on the PayPal button in the upper right corner of the window will attempt to start your browser and take you to the Amigift's PayPal site. Detailed info about the registration process can be found on that window. Clicking the "Cancel" button closes the window and leaves you behind with a bad conscience. :)

- Updates

This application menu item opens the AMIGIFT's Online Updater window.

What appears to be not much more than an empty listview is a feature that allows easy access to updates of AmiGiFT components and network-specific data (Read: node and banlist files).

The listview contains columns that display the component names, the versions available locally and remotely and some additional information about these. Having the daemon online, a click on "Receive list" connects to the amigift website and fills the listview with the information retrieved. Now you can select the components you would like to have updated by selecting them and clicking "Update Selected". Which ought to be done whenever a component has been updated. Getting up-to-date banlists from time to time is recommended as well.

The four checkmark gadgets in the lower left corner provide some extra comfort to the online updater:

- Update everything automatically

Does exactly that; whenever a newer version is detected remotely, the component present locally will receive an update.

- Backup files before updating

Renames the local copy of the component before the new version is installed, thus providing a backup in case the new version causes unexpected problems.

- Show only newer files

Changes the behavior of the listview. Normally, all components available will be displayed, regardless of version differences between local and remote copies. Checking this gadget restricts the list to those whose remote versions are newer than your local copies which may shorten the list.

infoNote: We only check for version and revision nmber changes only (eg: 2.0 -> 2.1), that means due the pre-release builds launched around GiFTMui isn't properly recognized as due as a pre-release version number does not change. If you are one of those using our beta builds you'll need to look at the program's DateStamp (filled on the 'Notes' column) and update it manually if you really want to use such betas.

- Check for updates on startup

Calls the online updater upon every start, thus ensuring you are aware of any new versions as soon as they become available.

The settings of the checkbox gadgets are saved along with the general giFTmui preferences upon exit.

- Iconify

Iconfies GiFTMUI, i.e. closes its window (and screen if applicable) and places an icon on your Workbench. Clicking this will restore the previous state. The iconification does not affect any operation of AmiGiFT, be it establishing connections, up/downloads or whatever.

- Quit

Quits GiFTMUI. Depending on your settings, giftd will receive a break signal or be left running in the background.



- Network

- Connect
- Disconnect
- Search
- Stop
- Download
- Shares

All those options are equivalent to the corresponding button in the toolbar.

- Inspector

The Inspector is an automated way of launching Locators, and what are locators, you ask? Locators are processes which looks for more sources for your active downloads, on a way that they don't stop downloading, read more about them on the preferences section.

If you want to abort a running Inspector, all you have to do is to launch it once again from this menu option and the running instance will be aborted.



- Daemon

- (re)Load

This option causes the daemon to loaded on a normal way or reloaded, if the daemon is already running (and we are connected to it) it will be first aborted by sending the apropiate command packet (not signaling it), Note this will not work if the daemon isn't to be run on your local machine.

- Quit

Removes the daemon by either sending its appropiate packet command or sending a break signal.



- Miscellaneous

- Unlink From Stack

This option will close all active sockets GiFTMui has in use, and later the bsdsocket.library will be closed as well. This could be helpfull (apart others) when e.g. MiamiDx sends a SIGBREAKF_CTRL_C signal to all applications which are still using the bsdsocket library, the first time GiFTMui receives such signal it will first 'Unlink From Stack' and if it receives a second ^C signal it will exit completely.




- Windows

- Reports

- Session

Equivalent to the "Stats" button in the toolbar.

- Overall

Opens the Transfer Statistics window that shows how many files have been uploaded and downloaded, their average size and at what average speeds the transfer took place. Additionally, the uptime of AmiGiFT can be seen here. All this information is divided into local and global values. Local means during the current session, global since the first start oof AmiGiFT.

- History

Opens the transfer history, a log about when which files were transferred and their sizes. Up- and downloads are shown on individual pages.

- Uploads Queue

Will give you an overview over files being requested from you. Since you will normally limit the number of simultaneous uploads from your computer, the result is an upload queue, i.e. any request beyond your limit will have to wait until a previous upload is completed. This queue can be displayed in various ways.


- Transfers Progress

- Transfers Windows

Equivalent to the "Transfers" button in the toolbar.

- Downloads Monitor

Opens the Downloads monitor window which basically shows the same information as the transfer window with the uploads being left out.

- Uploads Monitor

Opens the Uploads monitor window which basically shows the same information as the transfer window with the downloads being left out.


- FBrowser

On previous versions, the GiFTMui's FileBrowser was a simple listview with three buttons on top to select either the completed, incoming or shares directories. Starting with Version 2.0, the FileBrowser has become a little DOpus4-clone featuring main options like Copy, Move, Delete, etc - Additionally to the little implementation it looks like, it is 64-bit compliant and fully supports all kind of symlinks (soft/hard-links to files and dirs) apart other interesting internal features... following is a screenshot of it:

FileBrowser


regwarnThis feature is available for registered users only


- Debug

Opens a window with a simple listview where traces of the actions performed by GiFTMui are shown. Useful for troubleshooting and general info.

NOTE: The same contents of this window are saved to T:GiFTMui.log

- Chat

Opens the chat window to allow exchange of thoughts with other AmiGiFT users online.



- List

- Load

Loads a previously saved list into the main listview, replacing its current contents.

- Save

Saves the current contents of the main listview to disk, on a format to be loaded at a later time.

- Export

Saves the current contents of the main listview to disk being on a pre-formated HTML syntax to be viewable from any www-browser.

- Clear

Clears the main/current listview.



- Tools

- Check Ports

This causes AmiGiFT to connect to an internet service that checks the reachability of your computer on those ports required for your settings. This may be useful when trying to find the reason for problems establishing connections to one or more networks.

The check will be performed from a sub-process, so that you can continue using GiFTMui without problems at all, a busy bar at the top-left corder of your screen will be shown while the check is running, once finished a requester will show up with the port results.


The report will categorize ports as being in one of the following states:

  • Open: The port is accepting TCP connections and UDP packets. This means that an application is running that is using this port.
  • Closed: The port responds to probe requests but no application is using this port
  • Filtered: The port state cannot be determined because packet filters prevent probes from reaching the port
  • Unfiltered: The port is accessible but cannot determine if it is open or closed
  • Open | Filtered: cannot determine if the port is open or filtered
  • Closed | Filtered: cannot determine if the port is closed or filtered


- Create Cache

The Cache of GiFTMui are files where info about your current downloads are stored (regardless of the daemon's .state files, where giftd keep all the info required to manage a download), the data found into such cache files are:

  • URL: used to the download's file comment (set upon completion)
  • MIME: mime type of the download used to launch an associated player.
  • HASH: hash checksum of the file used to perform Locate procedures

There could be certain cases where your cache files become deleted or something.... using this option will try to re-generate the cache files, at least a HASH item is guarantee to be filled if the proper reading of the corresponding daemon's .state file was succesfull.

- Update Shares Index

This option will force the daemon to re-generate your shares index file (amigift:daemon/shares), note that you must be connected to the daemon to this to work.

infoNote: If you've added new folders to the sharing roots, and you want to update the index to reflect them, we'll recommended to use the ASIU program instead of this option, It should works lots faster than this due the running daemon launches a sub-process on the background with priority -1

- Verify Incoming

We are not perfect and may the daemon crashes at any time, if it's the case your download's state files may become renamed (in the process of updating them) causing once the daemon is reloaded to not recognize them. - This option will ensure all of the state files are properly recognizable by reading and checking your incoming folder.

infoNote: Obviously, the incoming folder configured into GiFTMui must match the one the daemon uses, and you must not be connected to the daemon and neither should it be running in the background!

- Torrents

This option opens the BitTorrent manager window, where torrent files (#?.torrent) are loaded and processed.



- Settings

- amigift

Equivalent to the "Settings" button in the toolbar.

- Load From...

Loads settings from a file previously created using "Save to...".

- Save To...

Saves the settings to a different file than the default.

- Read From Disk ALL

This option works in the same way as when you click 'Read From Disk' on the daemon and plugins settings pages, but it reads all of such settings at once. Usage of this option is required if for some reason ENVARC:MUI/GIFTMUI.cfg become deleted.

- Save To Disk ALL

This option works in the same way as when you click 'Save To Disk' on the daemon and plugins settings pages, but it saves all of such settings at once.

infoNote: This option is REQUIRED at a first amigift run by either you do not want to configure anything but use default settings OR once you've configured everything (use this option instead of clicking on each page button which obviously will be faster)

- Save

Saves the current settings to disk.

- Last Saved

Replaces the current settings by those last saved.

- Reset To Default

Replaces the current settings by default values.

- MUI

Opens the MUI settings.







  hand [ GENERAL USAGE ] Preferences Window  

top


Here we'll try to explain all of the configuration options. Indeed there are lots of options but don't get desperate... the default options set by GiFTMui at the first run should meet most users use, meaning what is really required to be changed/added are the sharing roots and protocols/networks you wish to connect to. (but don't get confused, even if the default options are ok for you, you'll still need to use 'Save To Disk' on the daemon and plugins settings, for a first run you could use 'Save To Disk ALL' from the settings menu and all of them will be saved to disk automatically in one step.)

infoNote: Each configurable option (MUI Object) is build with a bubble-help with the meaning/description of the option, just keep the mouse quiet over the object where you want to obtain additional info and the help will pop-up automatically.





  hand [ GENERAL USAGE ] Preferences Window / GiFTMui  


MAIN
main1

- Launch on startup

This option automatically launches the daemon on startup...as the label says, but this is no quite correct internally, on program startup what we try to do is a connection to the daemon port without matter if this option is enabled or no, if we are unable to connect to the daemon we'll then check the status of this option, if it's enabled the daemon will be automatically launched, else you'll be warned about the failed connection.

The connection attempt which is performed at startup is the same as if you manually click the Connect button, hence the same behavior about this option happens when you click the button yourself (e.g. disconnect -> connect).

Since the daemon could take some time to accept a connection (several seconds maybe) when launched by using this option, we'll not try to do a connection attempt each second or so but instead we'll benefit from the Message Ports functionality it has to send warnings and related messages to the GiFTMui's system port, we are talking about eg "protocol xyz succesfully loaded and initialized", once each of those messages are received a connection attempt to the daemon will be automatically performed, and so on until the connection is established. - If you are (or not) using the DAEMONWARNS tooltype do not matter here, since the message is received by GiFTMui as well just that it isn't notified, and as you may noticed there is a little bug... if you run the daemon in one machine and GiFTMui in other, in such case the auto-connections on this way will not work obviously, and you'll need to manually click the Connect button.

The options used to invoke the daemon process are below explained.

regwarnUnregistered users cannot de-select this option.


- Remove on exit

Using this option will cause the daemon to be shutdown when you exit from GiFTMui, if you are connected to the daemon at exit we'll remove it on a "sytem-friendly" way, else a break signal will be send to its process causing itself to be interrupted.

regwarn Unregistered users cannot de-select this option.







main2

- Open Transfers Window

The tittle says all. - whenever you request a download, or multi-downloads, the transfers window will be automatically opened. it may take a few seconds to the download to be added to the list though, thats because we send the download request to the daemon and then the daemon have to send us reply about the download was accepted/queued.

- Cut long filenames

It is known that todays certain files has very long names, such files could cause problems on the daemon side at time it's reloaded, thats because the filename most likely be truncated by the filesystem causing the daemon to not recognize such file at startup...

Using this option will forbid filenames longer than 77 characters, being the file's extension guaratee to be keep, of course. Thats assuming you're using SFS to the incoming folder, which is required.

- Add all sources

This switch causes, when a download is requested, to scan the list of results looking for more sources to the file about to be downloaded, only upto max sources will be added.   This option can be controlled from the main window results context-menu






main3

- Clear on new searches

When Multi-Lists aren't being used, this causes the list of results to be cleared upon new searches.

- Format bytes

Using this switch will cause sizes in byte notation to something else more human readable. (e.g.: "102547889" -> "102.5Mb")   This option can be controlled from the main window results context-menu

- Use Multi-Lists

Using this option multiple searches at once are possible, being a new listview opened for each of them.

regwarnThis option is available for registered users only







main4

- Confirm

When you try to quit GiFTMui you'll be asked for confirmation when this switch is enabled.

- Save settings

This option causes the MUI settings (ENVARC:MUI/GIFTMUI.cfg) to be saved to disk upon exit.

- Close first sub-lists

While working on Multi-Lists mode, using this switch will cause the active listview to be removed when you click the window's close-gadget.






main5

- Socket Activity

When this switch is enabled a new window will show up, where a trace of the negotation server <-> client are shown. (for debugging purposes).






main6

- Stats Interval

Specifies the interval time used to request statistics to the daemon, the daemon will reply us with the number of users and files currently available on each network, and the amount of GB being shared on it. This info is then computed and show on the main window title-bar, for details open the stats window.

- Max Sources

This slider controls the maximum number of sources to be added at once when requesting a new download, and when add all sources is being used.

- StandBy-Mode

This isn't currently being used. This mode was used on previous versions to keep the gui waiting while the daemon is busy rehashing your shares, todays such task is launched from a sub-process making this no longer needed. (The code has been keep for now though, if may become useful for some other purpose)






main7

The History is where we keep track of files we have downloaded or uploaded, you can access to it from the windows menu.
- Save On Exit

Causes the History to be saved upon exit.

- Save On New Entry

Causes the History to be saved upon new download or upload.

- FormatDate String

DateStamp formatting string to be used altogether with the file downloaded or uploaded. Its template is equal as for the FormatDate AmigaOS function, common codes (a few ones) are the following:
%c - same as "%a %b %d %H:%M:%S %Y"
%d - day number with leading 0s
%m - month number with leading 0s
%Y - year using four digits with leading 0s
%H - hour using 24-hour style with leading 0s
%M - the number of minutes with leading 0s
%S - number of seconds with leadings 0s
For full details check the Amiga's AutoDocs






main8

- Block all requester

Sometimes certain requesters may come up when you are not in front of your computer, you can enable this switch to avoid them from blocking GiFTMui...

- Do not handle timeouts

Instead of blocking all requesters, a timeout value can define when the requesters are automatically cancelled. When this switch is enabled timeout handling for requester are deactivated.

- Timeout

The timeout value to wait to requesters to be automatically cancelled.






main9

- Check TCP/IP Interface

Sometimes your internet connection may goes down without apparent notice to programs, such programs could then get blocked while resolving hostnames (usage of gethostbyname() function), to avoid such behavior from GiFTMui you can define here your internet interface, which will be checked before any socket-operation is about to be performed. Currently only Miami and Genesis TCP/IP Stacks are supported.





  hand [ GENERAL USAGE ] Preferences Window / GiFTMui  


EVENTS
events

Events are a group of settings giving you the chance to execute certain action(s) when something happens...

Brief explanation of the gagdet array: The checkbox controls whether you want something to happen when the named event occurs. The adjacent string gadget contains the sound sample you want to have played. It can be in any audio format you have a datatype for. The small gadget in the middle (the one showing two speaker boxes) gives you a playback of the chosen sound. The string gadget on the right side takes up a Shell/ARexx command you may want to have executed when the event occurs. The type of command is adjusted with the toggle gadget next to it.





  hand [ GENERAL USAGE ] Preferences Window / GiFTMui  


PLAYERS
players

Those settings allows you to play/display files right after the download is finished. This is the section where the matching player software for several filetypes is set. You can disable or enable all players at once by using the top-group CheckMark.

Filetypes are recognized based on their MIME type, which is determined by looking at the name extension of the downloaded file. (additionally, amigift is internally able to detect wrong file-extensions for common types (eg jpeg, gif, or mp3) by reading the header of the downloaded file, and warning you then if the file extension does not mach the guessed (real) filetype)

The individual checkboxes in each line control the support for the MIME type named in that line. The list begins with the most common MIME types, as show on the following table:

Format MIME type
MPEG video/mp#?
AVI/MOV video#?
MP3 audio/mp#?
OGG audio#?
Images image#?
Unknown all the rest


The handling of players are launched checking the mime types on the above order, so that if the file isn't in MPEG format (match against video/mp#?) we'll check next if it's some kind of video, meaning the player for AVI/MOV could really launch any type of video other than MPEG, same for audio types.

The next ten lines allow you to enter other filetypes you want to have identified and handled by the appropriate player. The string gadget on the left side takes up the extension (PDF, HTML or whatever), Note these player have priority over the above ones, meaning if you define a player for ".jpg" it will be launched instead the general player for Images.   The player programs either have to be in your DOS search path or have to be given with their full path to be found. The gadgets on the right side launch the entered program. A requester will open, asking you for a file that reflects the filetype in question. This way, you can check whether the chosen player is able to handle that sort of files.

infoNote: Make sure the player you choose is apropiate to be launched within GiFTMui... first, by checking if it works launching it from a shell, and then testing it from the preferences (right side button). Note also where the player is about to accept a filename from its command line should be replaced by %f (printf formatting style) which GiFTMui will use to place the file to be played.





  hand [ GENERAL USAGE ] Preferences Window / GiFTMui  


SOUNDS
sounds

Sounds settings are similar to Events, they gets played on certain actions. The handling is identical. The checkboxes control whether a notification should take place in that situation or not, the string gadget contains the sound file, the gadget on the right edge tests if the sound is audible.





  hand [ GENERAL USAGE ] Preferences Window / GiFTMui  


LOCATOR
locator

Locators are processes with the only job of locate more sources for your downloads, in a way that they don't stop downloading... Locators creates a new socket connection with the daemon, it send the locate request and waits for results (it's just like performing a normal search using the realm 'hash'), of course everything is handled automatically in the background, so that you can continue using GiFTMui without problems at all. Follow are the description for the settings:
- Launch Automatically

Locators will be automatically launched once a download reaches Zero sources.

- Handle Queue

When Locators are launched automatically, there could be the case where several of them are launched very quicly causing only the first instance to take effect - by that reason, from GiFTMui 2.0 (build #148) the avility to add them in a queue have been added, so that if e.g. you have 20 downloads and all of them reaches Zero sources, while locators are enabled, only the first request is handled in real-time being the rest queued to be automatically launched as well on timeout or end of results for the running instance.

- Allow multiples

This option is currently unavailable...

- Timeout

Specifies the maximum time-life a Locator is keep running.

- Inspector

The Inspector is an automated way of launching Locators, if it's Activated it will be launched given the interval value and it will check your list of downloads, unless Check all is enabled it will launch a Locator for transfers without sources, else (when Check all is enabled) it will launch a Locator for all of your downloads. - If you want to abort a running Inspector you'll have to "re-launch" it from the Network menu.

regwarnLocators are available for registered users only!






  hand [ GENERAL USAGE ] Preferences Window / GiFTMui  


DOWNCHECK
downcheck

Downloads Checker - if actived, when you try to download a file, the given path(s) will be scanned for identical files to ensure that you have not already downloaded it before. Paths are either added by entering them into in the string gadget below the list or choosing them via file requester. A path can be removed from the list by doubleclicking the entry.

- Activated

Switches the downloads checker on or off.

- Recursive

When checked, sub-directories of the given paths will be scanned as well.







  hand [ GENERAL USAGE ] Preferences Window / GiFTMui  


CHAT
chat

The chat is just a little IRC implemetation which connects to the freenode network and its channel #AmiGiFT.

See it, try it, love it! ;-)
- Connect to the chat

Controls whether a connection to the chat is established or not.

regwarnUnregistered users cannot de-select this option.


- Username & password

If you are a registered user of the freenode network you can enter here your details, and if you are not please enter at least your nick on the Username field!

- Channel logger

The checkbox controls whether the contents of your chat session will be logged or not. If you choose to log it, you can enter the path of the log file to be used to log entries to.

- Sound Events

Similar to the "Events" and "Sounds" pages, you can give some sound effects to be played on various occasions. The handling is identical. The checkboxes control whether a notification should take place in that situation or not, the string gadget contains the sound file, the gadget on the right edge plays the sound in a way to test if it's audible.







  hand [ GENERAL USAGE ] Preferences Window / GiFTMui  


SOCKOPTS
sockopts

The following options are directly related to socket operations, being just a brief description used, if you want to know more in detail you should take a look at the bsdsocket.library docs, which are available here. - Note that some of the following options may are useless for normal use, but added for debugging/test purposes.

- Modes

- FIONBIO

Control whenever non-blocking I/O should be used.

infoNote: Having FIONBIO enabled is normally a good idea, considering socket events and MUI stuff is handled from the same Task, meaning if you do not use it you may could notice certain slow down from the mui side at time of reaching user inputs...

- FIOASYNC

Control whenever asynchronous I/O should be used.

infoNote: There are know issues from most of our TCP/IP Stacks at time of handling asynchronous sockets with multiple connections at a time, our tests reveal that only MiamiDx does not have (apparent) problems from using it... it could be our fault, of course.. but it's clear this mode does not work on the same way from the various stacks we have...


- Options

- Send Queue

Using this option, packets to be sent to the daemon are queued if they are about to be sent very quickly so that the connection does not get congestioned... as for fionbio, this option is recommended to be keep enabled - it also avoid sending duplicated packets (eg STATS requests)

- Keep Alive

keep connections alive, enables the periodic transmission of messages on a connected socket.

- No Delay

This option disables the Nagle buffering algorithm when it's enabled, causing packets to be sent between server <-> client without delay... This should increment perfomance on certain cases, however it is mainly when small amount of data have to be sent as it increased bandwidth usage...

- Low Delay

This option is used to minimize delays on interactive traffic...whenever applycable...


- Fine Tuning

- RCVBUF

buffer size for input

- SNDBUF

buffer size for output

- RCVLOWAT

minimum count for input

- SNDLOWAT

minimum count for output

- RCVTIMEO

timeout value for input

- SNDTIMEO

timeout value for output







  hand [ GENERAL USAGE ] Preferences Window / giftd  

top

MAIN
detail_prefs_giftd_main1

- User Interface Connections

This is the hostname and port number the daemon is listen on to accept connections, This should normally be you local machine (IP address 127.0.0.1), being 1213 the default port number - Unless you have a special need to use a non-standard port, just accept the default.

- Allowed Connections

Space separated list of hosts to allow connection to the daemon (running default on port 1213). This protocol is used to the communication between daemon and client, and could be considered a security risk if you allow external connections.

The following special keywords are supported:

  • ALL is a synonym for 0.0.0.0/0
  • LOCAL is a synonym for 127.0.0.0/8 192.168.0.0/16 172.0.0.0/11 10.0.0.0/8

Bitwidth fields are optional






detail_prefs_giftd_main2

Command Line Options are options which are passed to giftd by either at the command line prompt (obviously) or as SystemTags()'s attributes. options follow explained:

- Disable Logging

giftd logs several different actions to the logfile amigift:daemon/giftd.log (mainly for debugging purposes), enabling this option will cause such log not to be generated.

- AsyncIO buffer

As above stated, from version 2.0 downloads are saved to disk by using asyncio.library, here you can define the write buffer (in bytes!) this library will use.

infoNote: That buffer size will be used for each of your downloads, meaning if you define here 1000000 and you has 10 active downloads, it will require then 10MB of free RAM.

- Enable Console Output

This option will let you be able to read interactively the contents of the amigift:daemon/giftd.log logfile in a console (eg CON:) window at your Workbench (or public screen).

If you enable the switch you'll have to provide a console window as well (no default one is available..), also, this option has no effect if logging is disabled.



- Priority

Here you can define at which priority do you want the daemon to be run.







  hand [ GENERAL USAGE ] Preferences Window / giftd  


DOWNLOAD
daemon download paths

- Incoming

Directory to store transfers while they are being operated on (downloaded). Temporary state files are also kept here. It is recommended, but not required, that the incoming and completed directories are on the same partition (drive), as above stated.

- Completed

Directory which will contain files after they have successfully finished downloading.







  hand [ GENERAL USAGE ] Preferences Window / giftd  


SHARING
detail_prefs_giftd_sharing

- Shares

List of fully qualified paths you wish to share. These directories will be recursed at giftd's startup and the files contained within will be subjected to an MD5 hashing. The results will be cached and will only be recalculated on a per share basis when the size or modification time in the cache and on disk disagree, or the file name is changed.

Sanity notice: Do NOT share source directories! Remote nodes will refuse to index your shares if you are attempting to submit more than 64000 files. - Also note that under lower powered machines high amount of files being shared (files, not MBs) could result on lost of connections due the time it could take them to be readed from disk and submitted.

Security notice: Do not share directories which may contain sensitive information, such as ENVARC: or S:. - Also note that any directories shared here will be stripped of all but the last path element when sub-mitted to other nodes for indexing, effectively "hiding" the directory prefix.



- Hidden extensions

Space-separated list of extensions whose files will not be shared.

- Resync Interval

Controls when giFT periodically rescans your shared directories for any changes (new files, missing files, changed files, etc.) and communicates those changes to the underlying protocols. This parameter specifies how often (in seconds) you want that to happen.

For your reference:
  • 0 turns off periodic auto-resync
  • 3600 one hour
  • 86400 one day
  • 604800 one week


- Max Uploads per user

Maximum amount of uploads allowed from the same user at any given time. It is recommended that you keep this at 1 in order to prevent users from unfairly queueing your connection.

- Max Uploads simultaneous

Maximum amount of simultaneous uploads allowed. Setting this to -1 will cause giftd to not limit outgoing transfers. 0 effectively disables sharing.

- Hide dot files

Determines whether or not to hide directories which contain a leading dot. These directories are commonly meant to be "hidden" and thus should not be submitted to the network.

- Share Completed

Controls whether or not giftd should automatically share files that you have finished downloading. This feature significantly improves the networks abudance of files and helps ease the load on those sharing popular files. It's a Good Thing (TM), please leave it on.

- Ignore incoming

Determines whether or not your incoming folder should be shared as well. Normally you should keep this option un-selected...

- Shares Hidden

Controls whether or not your list of shares shouldn't be transmitted to the supernodes (meaning, as a temporal way).







  hand [ GENERAL USAGE ] Preferences Window / giftd  


TUNNING
detail_prefs_giftd_tunning

- Down/up-stream bandwidth

Bandwidth throttling allows AMIGIFT to have some basic control over your bandwidth usage. This code operates in user space, and as a result can not guarantee perfect accuracy. If you wish to enable use this feature, please consider using a more reliable kernel space option first....

The configuration sliders control the maximum number of bytes per second allowed for the given stream direction. A setting of 0 ('unlimited') will disable throttling for that direction.



- Reports

This option tells the daemon when it should send transfers progress back to GiFTMui, under slower systems, it is not recommended to use a lower value than 2 seconds to avoid overhead... The minimum value for uploads could be even higher, and recommended.

Change Slip controls at which interval should the daemon report transfers progress when there is no data transfered, so that the GiFTMui's listview gets refreshed. Also, this is the value interval which states when the #?.state files need to be written/updated back to disk.







  hand [ GENERAL USAGE ] Preferences Window / giftd  


PROTOCOLS
detail_prefs_giftd_protocols

From this page you can select at which p2p networks do you want to connect to.






  hand [ GENERAL USAGE ] Preferences Window / OpenFT  

top

MAIN
detail_prefs_openft1

- Class Type

Node classification. This value is very important and will determine your role on the network.

The following settings are allowed:
  • 1 USER
  • 3 SEARCH
  • 5 INDEX
  • 7 SEARCH & INDEX

At time of this write, AMIGIFT only supports USER node types, hence you must not change this value, same applyes to the Class Allow value, whose default value of 3 must be keep.

- Default Port

Core listening port. OpenFT uses a compacted binary protocol for the core communication with other nodes. If this machine is unable to provide both port and http_port to the outside directly (blocked by either by a firewall or a NAT setup) you should select 0 here.

NOTE: If you are unable to route this port (along with the HTTP port) you will be unable to download from other users with that same inability. You will, however, maintain the ability to upload to other non-firewalled users. Selecting non-zero when the port is not available to the outside will cause very broken behavior, namely search results will be extremely unreliable.



- HTTP Server Port

OpenFT's implementation also makes use of HTTP for all file transfers. See above for more details. Please provide a valid port here regardless of your firewall state.



- Alias

Arbitrary name you'd like to associate with your node. This field is optional and it is NOT to be trusted. The name is not unique to the network. Please do not choose useless aliases.



- Max Active Connections

Maximum number of "active" nodes that are allowed connection at any given time. The default value (-1) is used to calculate a suitable value for most search nodes based on their current max child configuration and other parameters. If you wish to take on additional connections, please note that you must set your maximum file descriptor limit accordingly (provided that the internal setrlimit() call is unable to sufficiently increase your current limits). Consult your shell's manual regarding ulimits for more details.



- LAN Mode

OpenFT offers a special configuration for users who wish to operate a network from within a local area network (LAN). This mode causes giFT to reject authorization from any non-local address as well as advertising it's presence via the local UDP broadcast. If this switch is non-zero you will not be able to contact the main network.



- Host Allow

When LAN mode is enabled, this configuration switch is used to verify which hosts are allowed connection to the core OpenFT port. It is highly recommended that you just don't touch this, regardless of what lan_mode's value is.

NOTE: This switch provides a very crude loophole that could allow you to create a "private" OpenFT network between a list of known nodes. Using this "feature" is going to be quite cumbersome as it is intended to be used by developers only. You have been warned.






SEARCH
detail_prefs_openft2

The first group of settings (Childrens, DBPath, and Cache Size) are used while operating as a Node Class other than USER, Since (at time of this write) AMIGIFT only supports USER nodes, you shouldn't bother about those settings.

The rest of options from this page are considered for developers/testings purposes and/or undocumented, and therefore you should not change them. - However, if you are in need of fine tunning OpenFT please ask on our mailing-list for further info.






  hand [ GENERAL USAGE ] Preferences Window / Gnutella  

top

MAIN
detail_prefs_gnutella

- Port

Which port the Gnutella plugin uses. The default for the Gnutella network is normally 6346, but it is random for this plugin in order not to interfere with other Gnutella clients.

Unlike OpenFT, the Gnutella plugin uses a single port for both HTTP and protocol communication. Similar to OpenFT, this port must be reachable from the outside Internet if you want to download from firewalled users. Download and search result performance is much better when this port is reachable, as quite a fair number of hosts on the Gnutella network are firewalled.



- Class

Class type Gnutella should operate as - this is an internal/undocumented option as you should not change it if you don't know what you are doing...



- Connections

Number of connections we maintain while working as the different operational modes... This is an internal/undocumented option as you should not change it if you don't know what you are doing...



- Max Nodes

Maximum number of nodes we normally maintain...



- Proxy

Should the Gnutella plugin use an HTTP proxy server?

The Gnutella plugin will contact some websites over HTTP for finding an initial list of nodes. If you need to go through a proxy server to access websites, the plugin will fail to connect to the Gnutella network unless you fill in your proxy server here.

This field can be formatted as hostname:port, with an optional 'http://' prefix and optional trailing slash. For example, http://my.proxy.com:8080/ and my.proxy.com:8080 are valid.

Most people can probably leave this blank.






DEBUG
detail_prefs_gnutella2

Those options enables the various debug capabilities of the plugin,
if you need further info please ask on our mailing-list.





MISC1
detail_prefs_gnutella3

- Local

Those options controls whenever you want the plugin to operate from within a local area network (LAN), as previously explained to the OpenFT network.



- Handshake

Handshake timeouts are internal values keep configurable for testing purposes, you shouldn't need to change the default values.



- Transfer push max in limbo

This is another internal/undocumented option.



- Max (per user) Uploads

And another internal option made available for amigift, with this one you can define how many uploads per user are allowed, regarless of the giftd's global setting...






MISC2
detail_prefs_gnutella4

- Log Results

Enable all to print information about each search performed to the log file, and/or enable packets to print a line for each result packet generated to the log file. This line includes just the number of results in each packet.



- Hops As Meta

Whether to attach the number of hops each result travelled as a metadata field "Hops". Interesting to see but probably not too useful for the average user, and so disabled by default.



- Packet ascii logfile

Output to log ASCII Packets.



- Node List

How many connections attempts each maintain loop for nodes previously registered.



- Node Cache

How many connection attempts for nodes in the pong cache.





  hand [ GENERAL USAGE ] Preferences Window / FastTrack  

top

detail_prefs_fasttrack

- Username

Your username. FastTrack will not allow access to the network without a username. The username is not unique on the network and is not to be trusted. The username must not contain whitespaces!



- Port

The port FastTrack will listen on for incoming connections. Both TCP and UDP.



- Forwarding

If you are behind a NAT and you are forwarding the above port you have to enable this i.e. you forward outside_ip:port -> inside_ip:port outside_ip and inside_ip are determined automatically. Do not enable this if you are not forwarding.



- Allow Sharing

If enabled FastTrack will share files as configured with giftd. If disabled files will never be shared on FastTrack even if giftd shares on other networks.



- Banlist Filter

If enabled FastTrack will filter out all search results which come from ips matching the ranges specified in the file AMIGIFT:daemon/FastTrack/banlist



- Auto Search More

If Enabled FastTrack will automatically search again after a search has completed.





  hand [ GENERAL USAGE ] Preferences Window / Ares  

top

detail_prefs_ares

- Username

Your username on the network. Ares seems to make some effort to uniqify these, so you may not get exactly what you request. Leaving this blank will get you an anon_xxxxxxxx username.



- Port

TCP port to listen on. Be sure to forward this if you're behind a firewall or NAT.



- Sessions

Number of supernodes to connect to. Be sensible, please.



- Timeout

Timeout in seconds from the time the search was sent to the first supernode. After the search has timed out all further results will be ignored.





  hand [ GENERAL USAGE ] Preferences Window :: Remarks  


If you are using a 3rd party plugin (a plugin developed by a entity outside the AMIGIFT Project Team) it is something from that plugin's author to provide the proper documentation. If that particular plugin has configuration options, those must be provided by using a MCC (MUI Custom Class) which GiFTMui should be able to load from the plugins folder (refer to the development section for further info). If no configuration options are provided, or if there is a problem with the MCC, you'll see the following message:

detail_prefs_nosettings




Once you made modifications to the daemon and/or plugin settings you have to use 'Save To Disk' button, that's required due else the daemon will not be aware of the changes, if you forgot it, you'll be prompted with the following requester:

detail_prefs_changed

In the other hand, the usage of Read From Disk is just to avoid mistakes by de-sync situations, and you shouldn't need to use it if you do not edit the config files manually and while you're using GiFTMui's Save Settings Exiting switch option. Hence, if you usually edit the config files and/or do not save the MUI settings on program exit, you're required to use this button before making any change on each of the pages which contains this button. Also, isn't required either to use this button on the first GiFTMui run, since it has internally stored default options for quite everything, but keep it mind that if for some reason you need to manually delete the mui config file ENVARC:MUI/GIFTMUI.cfg, then indeed you must use this button on the next program run, resuming, you're encouraged to activate Save Settings Exiting switch and to not edit the config files manually (if isn't strictly needed) you were avoided headaches.. on the first run just go the preferences window and configure everything to fit your needs, use the objects bubble-helps if you need support to understand something, on most cases the default options will be ok probably, however do not assume that and take a moment to review what each option are for, you'll avoid more headaches later... Finally, once you finished configuring, click on Save To Disk for each of the page frame which contains this button, this will save the options to the config text-files which are later loaded by the daemon. If you need to configure several components (eg: It's your first program run) you could use Save To Disk ALL instead, from the settings menu, and all settings for the daemon and/or plugins will be saved on a single step.

You'll be prompted with the following requester when such a de-sync situation happend - here we just edited the giftd.conf and Ares.conf files to this to happens to take the screenshot:

detail_desync_changed

To give some more background on this, each of the preferences option has a Object's ID which MUI uses to save its contents to ENVARC:MUI/GIFTMUI.cfg upon program exit. The settings saved there are totally independient from the daemon/plugins configuration files and/or options, this can be interpreted as a safe-copy to them.. On program startup, and only once each reset, the settings stored into ENVARC:MUI/GIFTMUI.cfg will be compared against the daemon/plugins config files (AMIGIFT:daemon/giftd.conf and AMIGIFT:daemon/<plugin>/<plugin>.conf, where "<plugin>" is the network plugin name). If the comparison fails, you'll be instructed to use "Read From Disk", as shown on that requester, assuming such .conf files are the more recent and therefore the ones we should trust, that's unless there was a write error writing back to disk those daemon/plugins files, in such case you'll need to use "Save To Disk" instead to re-generate the corrupted file(s) - a bit some more info about this is provided on the FAQ.





  linetype [ GENERAL USAGE ] Transferences Window  

top
detail_transfers

That's the Transfers Window, where Downloads and Uploads are shown/processed (click on the image to enlarge it). Note COMPACTMODE Windows was being used at time of the screenshot. Here we have to mention that downloads and uploads lists are managed by the same MUI Custom Class, including those monitor windows accessed from the application menu, and the downloads list build into the main window, being each list working independiently from each other except that later one which inherit the actions performed on the Transfer's downloads list (and viceversa), but only while it's enabled to avoid some overload, as previously explained.

Well, we'll start explaining the Transfers Window from top to bottom, Starting with the ToolBar from left to right:

  • Abort All: This buttons lets you abort with one click either all downloads or uploads.
  • Cancel: Aborts the selected transfer (download, or upload)
  • Pause: Pauses the selected transfer.
  • Unpause: Resumes the selected transfer.
  • Stop: Stops the last transfer being played/previewed.
  • Play: Reproduces the selected transfer by using a player previously configured
  • locsrcs: Locate Sources for the selected transfer. Locators was previously explained
  • remusrc: Remove Transfers Without Sources. - This button lets you quick-remove all those transfers stalled without sources...

On the right side of the toolbar (without being part of it) you can see a little black cyrcle, it's an GIF Anim representing a radar, which is showed when a Inspector is running. That GIF Anim is loaded from AMIGIFT:Images/insact.gif and therefore freely changeable to something else you wishes.


Following the layout, here it comes now the main downloads list:

When more than a single download is found, an additional info bar at top of the downloads list will show up, as you can see on the screenshot. What you will read on that info bar is the following: On the left side, and only when a Locator is running, you will see something like Locating xyx (xx Queued) where xyz is the Download's Session Identifier (sesid column number, below explained), and hence, the download for what we are looking for more sources to download from. And, xx represents the number of "Locator Instances" waiting to be launched to locate sources for other downloads (but that only works if you keep Handle Queue switch option enabled, else the last running instance will be aborted when a new Locator is requested/launched).   On the right side, you'll find a Lamp which will be black when none of the downloads are active, green otherwise; next, the total number of downloads, followed by the number of active downloads, and the number of downloads without sources (and suitable then to launch a Locator over them)

...and the meaning of each of the columns:

  • SESID: Download's Session Identifier; The daemon assigns each transfer a unique identifier, valid to the current session only (on each run a new value is assigned). It may also needs a mention that the daemon only uses the upper bound of an 'unsigned short' type to that identifier, being the lower bound reserved for GiFTMui's searches.
  • File: The filename you are actually downloading.
  • Size: The size of that file.
  • Transmit: The amount of bytes already downloaded.
  • CPS: The current download speed.
  • State: The Global State for that download, Active/Paused/etc
  • Status: The Status for the peer connection currently being established, the status text will be replaced by the percent completed when the connection has been already established.
  • Chunk: Chunks represent the pieces of the file simultaneously being downloading (since we can download from several users at the same time, of course), this column shows the negotiation status on the last checked peer connection (read below about the Sources Window for further info), that text will be replaced by a gauge-like object when it's active and downloading, that object will graphically represent the amount of bytes transfered for that file - refer to the ChangeLog entry for 2005-09-16 for further info.
  • ETA: Estimated Time Arrival (countdown clock, really)
  • User: The user of the current and active chunk from where data is actually being downloaded.
  • Through: The network where that user was and we find him to download that file.
  • Sources: How many sources this download has. Red lamps represent a single source by lamp, half-green two sources by lamp, and green lamps represent three sources by lamp (being therefore upto 15 sources showed up)

The downloads list has its own context-menu as well, a tiny one at least, where you can find some of the same entries the Toolbar has, plus two additional ones:

  • Where is this file from? Thats the ShareMonkey service previously explained.
  • Sources: From this context-menu item you can access the list of sources a particular download has, understanding as "source" the peer (user) you are connected to and from where your desired file is being downloaded. Obviously, each peer connection works independently from each other, making it possible to download from several users/peers simultaneously, thats the so called Chunks system, where pieces of a file are transmitted on an async fashion determined by a start and end offsets pointing to the file handler.

    Following is a screenshot of the Sources List Window. You can use Double-Click over an entry to terminate the connection with that user...

    sources list

Continuing explaining the Transfers Window, next in the layout you can find a BetterBalance.mcc's object, which you can use to resize both lists. And next to that Balance object is the Uploads List, which we need not to mention since it works the same way as the downloads list does (as previously mentioned, all those lists are managed by a single MUI's private custom class)

regwarn NOTE: If some of the options/features aren't available to you, it's just because those are to registered users, please help us help you, support amigift today registering! :)



  hand [ GENERAL USAGE ] GiFTMui Tooltypes  

Following are the list of supported Tooltypes which you can change from the GiFTMui's icon file, note that some of those options are setable from the preferences window as well, but available from here since may those need to be used before the MUI application gets actually created. On the first run, those options from the preferences window will inherit the default values from those found as tooltypes.


Name Description Default Value
BWINDOWS If you want to use BWindows rather than normal (MUI-default) Windows. NO
CHUNKPROGRESS If you want to use a gauge-like object to transfers progress. Users of low-powered systems, who normally download lots of files simultaneously, may want to disable this. YES Registered Users Only
COMPACTMODE This mode creates the main window on a very nice fashion, grouping most used windows into that single window, as previously seen. NORegistered Users Only
DAEMONWARNS If you want daemon's warnings/errors showing up on the GiFTMui's debug window. YES
DTABLESIZE How many connections you want the daemon to manage, refer to the ChangeLog entry for 2008-01-24 for further info. 256
FIOASYNC If you want to use asynchronous I/O sockets. YES (while under MiamiDx, NO otherwise)
FIONBIO While enabled causes sockets to work in non-blocking I/O mode, which is highly recommended. YES
FORCE_REHASH If enabled, the daemon will check your shares on each startup, once a month otherwsie. NO
REQTIMEOUT The timeout used to requesters to get automatically cancelled. 45
SPLASHWINDOW If you want to use the SplashWindow to the Startup step. YES
SWEXIT If you want to use the SplashWindow to the Exit step. YES
TEAROFF If you want to use that MUI Custom Class... NO Registered Users Only
TOOLBARHVERT While using TEAROFF, this causes the toolbar to be horizontal or vertical movable. NO
USESENDQUEUE In the hope to get the daemon less congestioned, this option causes GiFTMui to use an internal queue where packets are stored before they are actually sent. YES
AUTOREADSAVE Handling of 'Read From Disk' and 'Save To Disk' will be perfomed automatically when requesters are about to pop-up asking for it. NO
TFSTATUS Controls whenever the main window's counter for all active transfers should be enabled/used. YES Registered Users Only
TRACKDLS This control if the Transfers Window's downloads list should include the info bar... YES Registered Users Only
CMAPSETUP Short for Compact-Mode ActivePage Setup. This is some MUI *hack* which while working on COMPACTMODE will handle objects's MUIM_Setup and MUIM_Cleanup switching between tabs (RegisterGroup Pages), and therefore starting/killing notifications and other setup/cleanup actions when the ActivePage isn't the visible one. NO Registered Users Only
WSEASYNC While FIOASYNC isn't activated, Socket events will still be handled asynchronously (Internally by GiFTMui itself), using this tooltype you can disable such async way, just in case you *really* need to for whatever reason... YES
NLSLEEP Similar to CMAPSETUP, This is another "hack" which will put "to sleep" NList(s) as possible to try to achieve a better perfomance, this is just done by using Quiet, Disabled, and GoInactive... NO Registered Users Only
MUICFG Use this tooltype to provide a filename where to store MUI settings, eg: MUICFG=AMIGIFT:GiFTMui.cfg - If no tooltype is provided it will fallback to the default ENVARC:MUI/GiFTMui.cfg YES


Not related to tooltypes, but we take this time to show and explain the appicons used by GiFTMui, a couple of them to the diferrent states. Those icons are located at AMIGIFT:Images/ and you are free to change them to anything else.

appicons

From left to right, Offline, Online, Downloading, Uploading, and both Downloading and Uploading.

When the daemon isn't running, the appicon used will be the default application icon (GiFTMui.info), while if it's running but you are not connected to it the appicon being used will be therefore the Offline one.





 

top toc prev next

Getting Started

Starting with Version 2.0, AMIGIFT is designed on a portable fashion, It requires no installation at all, just extract the archive somewhere (eg: RAM:) and start the application. Also note that starting with build #200 the MUI's configuration file no longer is required to be saved to ENVARC:MUI/, in fact it can be saved anywhere by using the newly introduced MUICFG tooltype, which now enabled by default and pointing to AMIGIFT:GiFTMui.cfg.

Additionally, from time to time when a new updates comes, you may will find individually packaged components if eg only a plugin needs to be updated. However, what is more feasible is those little updates available through GiFTMui's Online Updater.

Futhermore, what you'll find there are MC68020 optimized binaries, registered users will benefit from ServicePacks which includes each component compiled to the different Amiga Systems flavors, along bonus material.

Well, we'll start right now splaining the simple startup process...

It is a nuisance, but please take the time to read through the last chapters. That will give you an idea about the abilities of AMIGIFT on the hand and the complexity of it one the other. Also, make sure you has installed all 3rd-party requirements before continuing, if you lacks a couple of them you can try the AMIGIFT-deps.lha archive which install/updates all such components with just a click on the installer script (And available for OS3, OS4, and MOS).

Then go ahead, start GiFTMui. You will be shown a Welcome Message. Its contents should look familiar if you have read this doc carefully so far. Close that window, we are ready to prepare AMIGIFT for use now. Open the main configuration window by clicking on the "Settings" button in the toolbar. Now is the time to configure GiFTMui, the daemon and the plugins you want to use according to your wishes. Since you know the meaning of the options (You have read the last chapter, right?), you should know what to do. :)

but well, don't get desperate... you shouldn't need to change each option, since the defaults should be valid for most users, what you are really required to change are the following options:
  • giftd->sharing->shares Put some folder you wish to share.
  • giftd->Protocols Select at which networks you wish to connect.
  • GiFTMui->chat->username That will be your user/nickname on the chat, each of the plugins also has a configurable username to the network which you're encouraged to define!

When you change the settings's page, from a component to another, you'll be prompted with a requester about changed settings, as previously stated, on the first run click NO and go to change the rest of options, and once finished configuring everything you need, use the Save To Disk ALL function from the Settings Menu, and you're done configuring.

Next it's time to launch the daemon to connect to the network(s), just clicking the Connect button from the ToolBar does the job, but make sure a TCP/IP Stack is running at that time. (NOTE: if it's your first run and you're reproducing the actions as you read them here, do not launch the daemon yet until you read about the ASIU program below!).

When the daemon is run for the first time it will try to generate your local shares database which may cause your system to become unresponsive due to a high CPU and HD load. Each network protocol selected must read your files and generate an appropriate hash (MD5 or SHA-1 are the most common algorithms used) for the shares. You can think of these hash values as fingerprints of the files. These allow the daemon to find identical copies of a file to be added as sources for a download/upload.

So depending on number and size of files you want to share, this operation will most likely hog your CPU and harddrive for a while. If you choose not to do the initial database generation, well, you will have to do it later. There is no way to avoid it, sorry. Luckily, this has to happen only once in this dimension. The next time you run the daemon, only files that were added or changed will be hashed. Assuming that no overwhelming amount of data has been added to your shares, the process should not take that long any more.

If everything worked out well until here, you are ready to go!

It is sometimes common for certain files to give giftd trouble with its hashing and meta data extraction routines... If you suspect a problem with your share hashing you can examine the operation more closely using the following command:

shell> AMIGIFT:daemon/giftd INDEXONLY VERBOSE

and you're strictly encouraged to use this command firstly, once you've installed all components/plugins you wish to use, and configured some sharing roots (some directories whose files will be shared over the networks), Since the threads which are launched interactively has priority -1 and this could really take looong time for a first hashing procedure (depending of course, the amount of files and size to be shared) ...

Recently, a new application with name ASIU (Short for Amigift Shares Index Updater) was created, which simplifies this job. With a simple MUI Interface which contains a listview and three buttons you can add which paths you wish to share, or remove paths previously being shared. It will show files found on the selected paths and the amount of bytes (on a formatted fashion) as well.

Note that what it does is just a quick (user-friendly) way of launching giftd's shell process with the INDEXONLY argument, as previously noted, but with internal features to verify your config and update/fix it if needed, that includes activating all of your installed plugins (if aren't already) to create a full shares index file before launching the daemon, and restoring the config to your previous plugins once finished. It's highly recommended to use this program after a fresh boot for best perfomance, and obvioulsy without any other daemon instance running on the background (or without any other program in the background ;-)

If you are on your first run, we suggest you to run the ASIU program just after you used the Save To Disk ALL GiFTMui's aplication menu action. Once loaded, ASIU will show you the sharing roots you just have configured from GiFTMui, altogether with the number of files and bytes each path contains. (just a in time tip: if you're running amigift under a m68k machine do not try to share more than 800-1000 files or you'll be unable to connect to Ares..). Next by clicking "Update Shares Index" will generate your shares index database. Once it has finished working, you can continue with the launch daemon/connect step as above explained.


Well, we are now ready to do stuff, at this step you must have been generated your shares database file, and launched the daemon, if you have launched it from a shell you'll need to click the frontend's Connect button, else it is automatically connected.

As already mentioned, launching the daemon does not necessarily means it is ready to acccept connections. The same applies to network plugins, hence if you read those Plugin X has been successfully initialized does not means it has been connected to the network, this could take some time depending on various factors, read the next Maintenance section for more info about that.

You'll see when a plugin is ready to return searches when his lamp (from the frontend's main window) is green, clicking on the stats button, or if you run a single plugin from the main window title.

Last but not least, unlike previous versions, AMIGIFT 2.0 does not require the standalone AMIGIFT: assign, but it still uses it. That means the assign is automatically assigned on startup, by either GiFTMui or giftd. Even when it isn't required, you may want (or need, if some 3rd-part program uses eg amigift.library) to keep alive the assigns, in such case, add the following lines to your user-startup file:
Assign >NIL: AMIGIFT: <where-you-extracted-the-package>
Assign >NIL: LIBS: AMIGIFT:LIBS ADD

infoNote: Users of Miami(Dx) will notice FIOASYNC is enabled by default on the first run, if you later switch to another TCP/IP Stack you'll need to manually deactivate this switch.

Firewalled, or being a NAT, users must allow access to the follow ports:

  • 1213 daemon port, allow access to your local network.
  • 1214 UDP and TCP, used by the FastTrack plugin.
  • 1215 TCP only, used by the OpenFT plugin.
  • 1216 TCP only, used by the OpenFT plugin.
  • 6346 TCP only, used by the Gnutella plugin.
  • 59049 TCP only, used by the Ares network plugin.
These are the default port numbers assigned to each protocol, however they are fully configurable by you to anything else, without that interfering on the properly functioning of the network(s).

As an example on how you may could easyly configure your router, is by assigning the ports in a range, as show in the image below:

firewall example
(Click the image to enlarge it)


...And that's all to the getting started step. Confused? ask us!




 

top toc prev next

Maintenance

Remember that most peer-to-peer networks are not perfect and may often need a little nudge from users to keep them operational. Specifically, you need to make sure the protocol plugins have the necessary caches of nodes which they will use to make their initial entry into the network. If this file is largely out of date (especially if you haven't used AMIGIFT in a while) then it is likely you will not be able to find a new node to connect to and thus it will seem that AMIGIFT is doing "nothing".

To correct this problem you may need to examine the contents of your AMIGIFT:daemon/{plugin} directories and replace the nodes or cache files that are appropriate. For example, you can replace OpenFT's local nodes cache with the global default provided by us by simply removing the AMIGIFT:daemon/OpenFT/nodes and starting the daemon (do not remove while it is running). This may or may not provide a higher quality nodes file depending on the age of your OpenFT version and other factors..

"Protocol X cannot connect, what's wrong?" is certainly the most frequent (and most annoying) question that we receive, so I'm going to force all you to choke on a little background information before I even attempt an answer.

First, it is important to understand that giftd provides a framework for third-party plugins in which to nest, but it does not actually control how those plugins work, or develop. For this reason, the upstream AMIGIFT developers often have no idea why some unknown/foreign protocol plugin is not working exactly as you might expect. Naturally, you should contact the appropriate development team when attempting to request support...

Second, a common property of most peer-to-peer networks is the extremely limited availability of peers and peer resources. This often means that new users will be devalued and may require additional time to connect, or may not even be able to connect at all when the most localized group of nodes is unable to accept connections. This is especially true with smaller networks like OpenFT which do not have a large probabilistic network to poll from when certain sections become stressed. Yes, it sucks, we know this. The few things we can do to improve the situation are constantly being explored and worked on, but as is a common theme with most open source projects, we simply don't have the time to do everything!

And now finally the answer... Each protocol plugin has its own method of node discovery and propagation (as do most networks, independent of their giFT-API implementations), which means that there is no one unified answer to this question. For OpenFT you can often find a more up-to-date nodes file to replace the default by using the GiFTMui's tools menu, or starting with Version 2.0 you can use the new online updater facility. Please note that this method does not guarantee a network connection! You should consult the appropriate network plugin documentation (if any exists) and find the answer in the context of that plugin.


 

top toc prev next

Development



This section is somehow focused to developers who wish to know more about AMIGIFT internals. However, note this is an end-user documentation and therefore we'll not give a in deep documentation on development, just the very basics on how you can get started...

Starting with the GUI part, what GiFTMui basically needs to work with new plugins is just a MUI's Public Custom Class (.mcc) located inside the AMIGIFT:PlugIns directory, this class could be a subclass of whatever you want, but obviously the quicker way would be creating it as a subclass of MUIC_Group, it should return a valid MUI Object which will be placed as a children of a PageGroup on the preferences window.

The class will allow end-users to configure your plugin (similar to what happens with MUI's MCPs, which are used to configure Public MCCs, in this aspect you could see GiFTMui as a MCC and your PlugIn.mcc as a MCP ;), your plugin.mcc should additionally handle the reading and writing of the corresponding giftd-style's config file (those found into/as AMIGIFT:daemon/<plugin>/<plugin>.conf), as them are available for the rest of plugins as well.

There is provided a Demo.mcc and Demo.PlugIn (with full source code, of course) which demostrates how this works, The Demo.PlugIn source is just a quickstart on how to write PlugIns, but for better info and examples the OpenFT sources are the best choice.

NOTE that how GiFTMui will handle your plugin is based on the plugin's filename as found into the AMIGIFT:PlugIns/ folder, and the *.mcc and image (logo) based on that name, e.g. it founds into AMIGIFT:PlugIns a file named BacaBurra.PlugIn then it extracts the name and stores it as "BacaBurra" (case sensitive!, at least for MUI..), then it tryes to load the mcc using:

MUI_NewObjectA("AMIGIFT:PlugIns/BacaBurra.mcc", NULL);

(additional tags support may come later if needed, just request it if you need them..)

And then the logos loaded as well as:

AMIGIFT:Images/networks/normal/BacaBurra.iff
AMIGIFT:Images/networks/small/BacaBurra.iff

(being fixed width/height a requirement, 32x32 and 16x16 respectively)

Note that giFTMui will still work with your plugin if neither the MCC nor the logos are found!, what we understand as your plugin needs no configuration, being the logo replaced with a build-in image (with a "?" sign) if yours aren't found.

If you create a MCC, you'll need to implement the following MUI Methods on your class dispatcher:

#define MUIM_GIFTMUI_MCCLOADCONFIG 0x800FF00A
#define MUIM_GIFTMUI_MCCSAVECONFIG 0x800FF00B

Such methods will be invoked by GiFTMui when a user uses "Save To Disk ALL" or "Load From Disk ALL" menu options. be aware you must return the same method-id if your function succeed, and something else otherwise.

As you could see, how GiFTMui handles plugins is quite easyly, as seen for MCCs, regarding how to create network plugins, we encourage you to take a look at the sources for other plugins, specially OpenFT, as previously stated, you'll learn a lot more than what we can explain right now here... Since this is a end-user documentation (quite long already, indeed) we'll not enter in more details on development, but you are of course invited to join our mailing-lists where you are free to ask for anything you wish to know, or contact the author(s) directly if you prefer this way.


 

top toc prev next

Acknowledges, and Final Notes



AMIGIFT is a derived work from the giFT Project

Without giFT, AMIGIFT wouldn't exists at all.

Special Grettings and Thanks goes to the people who created plugins for giFT:

OpenFT Implementation is © 2003 Josh Guilfoyle
FastTrack Implementation is © 2003 Markus Kern
Gnutella Implementation is © 2003 Craig Barnes
Ares Implementation is © 2004 Tom Hargreaves


GiFTMui uses MUI object library © 1992-2008 by Stefan Stuntz

Without MUI, GiFTMui wouldn't exists.

Special Thanks goes this time to the people who created MUI's Custom Classes:

BetterBalance.mcc, and Lamp.mcc are © 1998 by Maik Schreiber
BetterString.mcc is © 1997-2000 by Allan Odgaard
Busy.mcc is © 1994-1997 by Klaus Melchior
BWin.mcc, UrlText.mcc, and GIFAnim.mcc are © by Alfonso Ranieri
GuiGfx.mcc is © 1999-2000 by Matthias Bethke
NList.mcc is © 2001-2007 by NList Open Source Team
TearOff.mcc is © 1998-2000 by Szymon Ulatowski
TextInput.mcc is © 1997-2001 by Oliver Wagner
ToolBar.mcc is © 1998-2003 by Benny Kjaer Nielsen

This product includes software developed by the
University of California, Berkeley and its contributors.

AMIGIFT 2.0 was brought to you by Diego Casorran, with the constant
and invaluable help from our betatesters Franco 'Framiga' Coccini,
Philippe 'mrod' Bovier, Krister 'Kicko' Skrtic, and Philippe 'Elwood' Ferrucci.

Also, Thanks to the graphic artists who directly or indirectly helped with
amigift: Bojan Milovic, Martin Merz, and Kenneth E. Lester Jr.
And to our current translators, Samir Hawamdeh and Hans-Jörg Ottinger.


THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

a more up to date version of this documentation can be found at http://amigift.sourceforge.net/docs/

for everything else amigift-related, go to its official website:
http://amigift.sourceforge.net/





   _____     _____  .___  ________._________________________
  /  _  \   /     \ |   |/  _____/|   \_   _____/\__    ___/
 /  /_\  \ /  \ /  \|   /   \  ___|   ||    __)    |    |   
/    |    |    Y    \   \    \_\  \   ||     \     |    |   
\____|__  |____|__  /___|\______  /___|\___  /     |____|   
        \/        \/            \/         \/               
                                   Connecting people ;-)    







 $Id: index.php,v 2.0 2009/08/06 22:47:32 diegocr Exp $