AMuleWeb PHP
Contents
aMuleWeb PHP manual
This page is in unfinished state. Information may be missing, inaccurate, misspelled or all of them
Introduction
aMuleWeb is an add-on program, used together with aMule and serves as webserver, allowing user to control aMule through browser interface. aMuleWeb works very similar to regular and wide-known webservers such as Apache[1] - set of HTML pages stored on server side (called "template"). Those pages contains embedded server-side script, which is running when user requests the page. Resulting page is returned to user.
The scripting language, aMuleWeb using is very similar to widely known "PHP", developed and distributed by Zend company [2]. Since aMuleWeb implementation is differ from original PHP, I will call it "aMuleWeb PHP" for reader convenience. "The PHP" language, will be referred as "real PHP" or just "PHP" to make difference between the two.
Conventions
Language elements, reserved words are marked bold: keyword. Things that are not part of syntax, but are reserved or predefined marked bold italic: special_var. Languge limitations marked like:
- Making cofee not supported
Interaction with PHP and webserver
Similarly to real PHP, script is embedded into regular HTML pages using <?php ?> marks. Page must have .php extension in order to be searched for script. Note, that markups can not be nested, i.e. placing <html> marks inside of <?php ?> will result in syntax error.
Core language constructs
aMuleWeb PHP have same basic language elements as real PHP version 5. Several things supported or implemented differently: OO constructs (classes) may pass syntax check, but they are not supported in any way. include construct is parse-time directive (in contrary to PHP, where you can do it in run-time and check result of "include" operation) There's no list at all.
Variables
There's scalar (referred as $var) and array (referred as @var) variables. Similarly to real PHP all variables are local, unless defined otherwise. Variables, marked as global must be declated before this definition. Example:
$a = 1;
function foo()
{
global $a;
}
References to variable and to array members are fully supported:
$a = &$b; $c = &$c[5];
- Reference of variable by name like $$var is not supported.
- Integer variables are 64-bit unsigned integers
- Variable substitution inside of "" is not supported.
Operators
All PHP operators supported. Implicit type conversion is supported too, as common in scripting languages. This way 1 + "2" = 3.
- Prefix and postfix ++ and -- are not distinguished (prefix form used)
- Using operator + for array mean "join" in real PHP. Here array is interpreted as integer equal to number of elements.
Subroutines
function construct is fully supported. In contrary to regular PHP function must be defined prior calling. It is error to do otherwise. Functions can be recursive, thou. Real PHP allows to omit parameters for function calls (default parameters). aMuleWeb PHP does not support this conventions, which mean that all parameters must be present when function is called. This is not an error, and parameters will receive predefined values when omit: 0 for numbers, "" (empty string) for strings. Parameters can be references or arrays with usual meaning.
- Function can not return reference.
Library
PHP language is known to have huge library of useful subroutines. Those subroutines are used to perform various tasks, varying from simple string manipulation to complex databases and OS binding. aMuleWeb PHP on the other hand, have very limited library. There's several reasons behind this fact. First of all, it is out of question to completely re-create PHP library, given it's size and complexity. Second, and most important, it's not really needed. aMuleWeb PHP is built to serve very specific application, and used to create very specific kind of pages. It will not be used to create e-commerce site or webmail. List below summarize supported functions:
- var_dump($var): var_dump()
- strlen($string):strlen()
- usort($var): usort()
- isset($var): isset()
Predefined global variables
Similarly to real PHP, there's set of special, or predefined variables, which have special meaning. Those variables may indicate input received from user, or they may control script execution. Those variables have same name as in real PHP, but functionality may be limited.
$_SESSION: Hash of values that survive between engine invocation per session. Some of it's values are predefined by webserver itself.
- $_SESSION["guest_login"]: set when password supplied belongs to low-right user
- $_SESSION["login_error"]: set when bad password supplied.
- $_SESSION["auto_refresh"]: always set; indicate time to autorefresh (in seconds). Can be used in http-equiv:
<?php
if ( $_SESSION["auto_refresh"] > 0 ) {
echo "<meta http-equiv=\"refresh\" content=\"", $_SESSION["auto_refresh"], '">';
}
?>
$HTTP_GET_VARS: Hash of values passed from browser on GET or POST method
aMule binding
The whole purpose of aMuleWeb control aMule. aMuleWeb PHP provide library functions for convinient access to underlying aMule datastructure for both queries and actions.
amule_load_vars: Query aMule datastructure. Result is returned as array of hashes, where each hash represent item in aMule datastructure (upload, download, client, item in search result). Following are possible category names:
- 'downloads'
- 'uploads'
- 'searchresult'
- 'shared'
- 'servers'
- 'stats_graph'
- 'stats_tree'
$var = amule_load_vars($name_of_variable)
foreach ($var as $i) {
}
Some info about data structures retrieved via amule_load_vars
downloads: return an array of Object(AmuleDownloadFile). The fields of this are:
- 'name' (full name with extension)
- 'short_name' (the full name trucated after some chars and ended with three periods)
- 'size' (in byte)
- 'size_done' (completed bytes)
- 'size_xfer' (transfered bytes)
- 'speed' (actually download speed, in bytes/sec)
- 'src_count' (total number of source found)
- 'src_count_not_curr' (number of sources not fully identified and connected to, so for total of valid source you use src_count - src_count_not_curr), src_count_xfer (source transfering in this moment), src_count_a4af (sources not used because used for another file)
- 'prio' (priority of downloading where 0 => "Low", 1 => "Normal", 2 => "High", 3 => "Very high", 4 => "Very low", 5=> "Auto", 6 => "Powershare")
- 'prio_auto' (boolean, 0 = false, 1 = true)
- 'status' (where 7=stopped / paused, for other status valute the transfer rate or src_count_xfer, if it's 0 status=waiting, else downloading'. Actually I don't know how distinguish from 'stopped' and 'paused')
- 'link' (full ed2k link, be aware: it included you ip as sources)
- 'hash' (univoque id of the file, is used for other commands)
uploads: return an array of Object(AmuleUploadFile). The fields of this are:
- 'name' (full file name with extension)
- 'short_name' (the full name trucated after some chars and ended with three periods)
- 'xfer_up' (total of uploaded bytes of this file to this client)
- 'xfer_down' (total of downloaded bytes of this file from this client)
- 'xfer_speed' (actual upload speed of this file to this client, in bytes/sec)
amule_get_categories': return list of valid categories
$cat_list = amule_get_categories();
amule_get_options': return options and their values. Options are returned in form of hash, where keys are categories and values are hashes of name-value for each option. amule_set_options($opt_values_hash)': set aMule options. Receives hash in form returned by amule_get_options'
amule_do_server_cmd': amule_do_add_server_cmd': amule_do_download_cmd': amule_do_shared_cmd': amule_do_reload_shared_cmd': amule_do_search_download_cmd': amule_do_search_start_cmd': amule_do_ed2k_download_cmd': amule_get_log': query log from aMule
$log = amule_get_log(); echo "My log:", $log;
amule_get_serverinfo':
Authentication
Real PHP have wide range of authentication and session management possibilities. In aMuleWeb PHP, status is different. Both authentication and session management are not part of scripting language. Instead, they are implemented as part of in webserver itself, and running invisibly for script engine.
Errors and debugging
As in any other language, aMuleWeb PHP have 3 types of errors: compile-time, run-time and logic errors. All error messages produced by engine are printed to terminal. This effectively means, that aMuleWeb should be started manually from terminal (and not automatically by aMule) in order to see those messages. Alghouth engine perform some effort to recover from syntax errors, it's known to crash in some corner-cases. Beware.
- Compile-time errors means error in script syntax as misspelled names, missing ";" or mismatched (). In this case, error message from parser is printed and execution is not performed.
- Run-time errors like division by zero, incorrect or missing parameters etc. When encountered, appropriate message is printed, and execution aborted in point of problem.
- Logic errors: everything is OK, but result is different from expected. Since aMuleWeb PHP offers no debugger, the only way to trace program is to add var_dump() in suspicious places;
It is possible to compile aMuleWeb PHP engine standalone. This compilation mode is used to debug engine itself. Since aMule binding is not possible in this case, it have little use for template debugging.
