AMuleWeb PHP

From AMule Project FAQ
Jump to: navigation, search

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 and reserved words are marked bold: keyword. Things that are not part of syntax, but are reserved or predefined are marked bold italic: special_var. Language limitations are 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:

If the aMule webserver was built with native language support enabled:

  • _($message) and gettext($message): gettext()
  • gettext_noop($message)
  • ngettext($msgid1, $msgid2, $n): ngettext()

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.

  1. $_SESSION["guest_login"]: set to 1 when password supplied belongs to low-right user, 0 otherwise
  2. $_SESSION["login_error"]: set when bad password supplied, normally is an empty string.
  3. $_SESSION["auto_refresh"]: always set; indicate time to autorefresh (in seconds). User can supply a zero. 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

Functions

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_do_shared_cmd

Description
void amule_do_shared_cmd(string $file_hash, string $command, [int $priority])

Used to change the priority of a shared file. The priority can be either increased, decreased or set directly.

Parameters
  • $file hash: identifies the file which the command is applied to.
  • $command: can be either "prioup", "priodown" or "prio". The "prioup" command increases the priority in the order very low, low, normal, high, very high, powershare, auto(, very low, ...). The "priodown" command decreases priority. When the "prio" command is used, $priority is a required parameter.
  • $priority: is used to set the priority directly. Allowed values are 4 = very low, 0 = low, 1 = normal, 2 = high, 3 = very high, 5 = powershare, 6 = auto.

amule_do_reload_shared_cmd

Description
void amule_do_reload_shared_cmd()

Used to reload the list of shared files fom disk.

amule_do_download_cmd

Description
void amule_do_download_cmd(string $file_hash, string $command, [int $priority])

Used to change a parameter of a file in the downloads list.

Parameters
  • $file hash: identifies the file which the command is applied to.
  • $command: can be "pause", "resume", "cancel", "prio", "prioup" or "priodown". When the "prio" command is used, $priority is a required parameter.
  • $priority: is used to set the priority directly. Allowed values are 0 = low, 1 = normal, 2 = high, 6 = auto.

amule_kad_connect

Description
void amule_kad_connect(string $bootstrap_ip, string $bootstrap_port)

Used to connect to the Kad netork.

Parameters
  • $bootstrap_ip: The IP-address to bootstrap from when connecting to the Kad network.
  • $bootstrap_port: The port to connect to.

amule_do_add_server_cmd

Description
void amule_do_add_server_cmd(string $server_addr, string $server_port, string $server_name)

Used to add a server to the server list.

Parameters
  • $server_addr: The IP-address of the server for connecting to the ed2k network.
  • $server_port: The port to connect to.
  • $server_name: Name of the server.

amule_do_server_cmd

Description
void amule_do_server_cmd(string $server_ip, string $server_port, string $command)

Used to connect to or disconnect from a server or to remove a server.

Parameters
  • $server_ip: The IP-address of the server
  • $server_port: The port of the server
  • $command can be "connect", "disconnect" or "remove".

amule_get_stats

Description
array amule_get_stats()

Used to query the status of aMule.

Return values

Returns an associative array with the keys: "id", "serv_addr", "serv_name", "serv_users", "kad_connected", "kad_firewalled", "speed_up", "speed_down", "speed_limit_up", "speed_limit_down".

  • "id": your ID.
  • "serv_addr": The IP-address of the ed2k-server you are connected to.
  • "serv_name": The name of the ed2k-server you are connected to.
  • "serv_users": The number of users connected to the server.
  • "kad_connected": 1 if you are connected to the Kad network, 0 otherwise.
  • "kad_firewalled": 1 if Kad is firewalled / ports are not properly forwarded, 0 otherwise.
  • "speed_up": Current upload speed in bytes per second.
  • "speed_down": Current download speed in bytes per second.
  • "speed_limit_up": Upload speed limit in bytes per second.
  • "speed_limit_down": Download speed limit in bytes per second.

amule_get_categories

Description
array amule_get_categories()

Returns list of valid categories.

Return values

Returns an associative array, the key is an index starting from 0 (= all), the value is the full name of the category ('all' is the 0-indexed, others may be "film", "Docs", etc...)

Programming example
$cat_list = amule_get_categories();
foreach($cat_list as $key => $cat_string) {
 echo "cat = ". $cat_string ."- key = ". $key;
}

amule_get_options

Description
array amule_get_options()

Returns options and their values.

Return values

Returns an associative array with the keys: "nick", "connection", "files", "webserver", "coretweaks".

  • "nick": Your nickname on the ed2k network.
  • "connection": Value of "connection" is an associative array with the keys: "max_line_up_cap", "max_line_down_cap", "max_up_limit", "max_down_limit", "slot_alloc", "tcp_port", "udp_port", "udp_dis", "max_file_src", "max_conn_total", "autoconn_en", "reconn_en".
    • "max_line_up_cap": Network connection upload bandwidth in kB/s.
    • "max_line_down_cap": Network connection download bandwidth in kB/s.
    • "max_up_limit": Upload bandwidth limit in kB/s.
    • "max_down_limit": Download bandwidth limit in kB/s.
    • "slot_alloc": Allocated bandwidth per upload slot in kB/s.
    • "tcp_port": TCP port to use.
    • "udp_port": UDP port to use.
    • "udp_dis": Enable or disable use of UDP port.
    • "max_file_src": Maximum number of sources per file in download queue.
    • "max_conn_total": Maximum number of total connections.
    • "autoconn_en": Autoconnect on startup.
    • "reconn_en": Reconnect on connection loss.
  • "files": Value of "files" is an associative array with keys: "ich_en", "aich_trust", "new_files_paused", "new_files_auto_dl_prio", "preview_prio", "new_files_auto_ul_prio", "upload_full_chunks", "first_last_chunks_prio", "start_next_paused", "resume_same_cat", "save_sources", "extract_metadata", "alloc_full", "check_free_space", "min_free_space".
    • "ich_en":
    • "aich_trust":
    • "new_files_paused":
    • "new_files_auto_dl_prio":
    • "preview_prio":
    • "new_files_auto_ul_prio":
    • "upload_full_chunks":
    • "first_last_chunks_prio":
    • "start_next_paused":
    • "resume_same_cat":
    • "save_sources":
    • "extract_metadata":
    • "alloc_full":
    • "check_free_space":
    • "min_free_space":
  • "webserver: Value of "webserver" is an associative array with keys: "use_gzip", "autorefresh_time".
    • "use_gzip":
    • "autorefresh_time":
  • "coretweaks": Value of "coretweaks" is an associative array with key: "max_conn_5sec".
    • "max_conn_5sec":

amule_set_options

Description
void amule_set_options(array $options_hash):

set aMule options. Receives hash in form returned by amule_get_options()

Parameters
  • $options_hash:

amule_do_search_download_cmd

amule_do_search_download_cmd($file_hash, $cat): Used to download 1 of the search results.

amule_do_search_start_cmd

amule_do_search_start_cmd($search, $ext, $filetype, $type, $avail, $min_size, $max_size):

amule_get_log

amule_get_log($rst): Returns log if $rst = "0", resets log otherwise. 

$log = amule_get_log();
echo "My log:", $log;

amule_get_serverinfo

amule_get_serverinfo($rst): Request contents of server info if $rst = "0", resets contents otherwise

amule_do_ed2k_download_cmd

amule_do_ed2k_download_cmd($link, $cat): Download ed2k link. Params: link, category (default=0)

amule_load_vars

Description
array amule_load_vars(string $command)

Query the aMule datastructure. Result is returned as an associative array of hashes, where each hash represent an item in the datastructure (upload, download, client, item in search result).

Parameters
  • $command: can be one of the following: "downloads", "uploads", "searchresult", "shared", "servers", "stats_graph", "stats_tree"
Return values
  • When $command is "downloads", amule_load_vars returns an array containing the currently downloading files. The keys and values are:
    • "name": Full name of the file with extension.
    • "short_name": The full name trucated after some chars and ended with three periods.
    • "hash": Unique id of the file, is used for other commands.
    • "progress": A png image displaying the parts of the file that are done, downloading, available and such.
    • "link": Full ed2k link, be aware: it included you ip as sources.
    • "category": Id of the category of the file, where 0 = all, 1 = first category, etc... see amule_get_categories
    • "status": Indicates the status of the file, where 0 = ready, 1 = empty (?), 2 and 3 = hashing the file, 4 = an error occured, 5 = insufficient disk space, 6 = unknown, never happens, 7 = stopped or paused, 8 = completing (copying the file), 9 = download complete, 10 = allocating full disk space needed for the file. When status = 0, evaluate src_count_xfer, to determine whether the file is currently downloading or waiting. When status = 7, evaluate src_count to distinguish between stopped and paused. A stopped file has 0 sources. A file which has 0 known sources can also be paused but the effect is the same.
    • "size": File size in bytes.
    • "size_done": Part of the file that is downloaded and not corrupted.
    • "size_xfer": Transfered bytes. This can be less than size_done when the file is compressible.
    • "speed": Actual download speed, in bytes per second.
    • "src_count": Total number of source found.
    • "src_count_not_curr": Number of sources not fully identified and connected to, so for total number of valid sources you use "src_count" - "src_count_not_curr".
    • "src_count_a4af": Sources not used because they are used for another file.
    • "src_count_xfer": Sources transfering data to you at this moment.
    • "prio": Priority of downloading where 0 = low, 1 = normal, 2 = high, 3 = very high, 4 = very low, 5 = auto and 6 = powershare.
    • "prio_auto": Whether the priority is automatically determined based on the number of available sources. (boolean, 0 = false, 1 = true)
    • "last_seen_complete": Date when the file was last seen and all parts of it available with at least 1 source. (Unix timestamp format)
  • When $command is "uploads", amule_load_vars returns an array of the currently uploading files. They keys and values 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 per second.
  • When $command is "shared", amule_load_vars returns an array containing the currently shared files. The keys and values are:
    • "name": Full name of the file with extension.
    • "short_name": The full name trucated after some chars and ended with three periods.
    • "hash": Unique id of the file, is used for other commands.
    • "size": File size in bytes.
    • "link": Full ed2k link, be aware: it included you ip as sources.
    • "xfer": Bytes transferred during this session (Since aMule was started)
    • "xfer_all": Total number of bytes transferred (Since file was first available)
    • "req": Number of requests for this file during this session.
    • "req_all": Total number of requests for this file.
    • "accept": Number of accepted requests for this file during this session.
    • "accept_all": Total number of accepted requests for this file.
    • "prio": Priority of uploading where 0 = low, 1 = normal, 2 = high, 3 = very high, 4 = very low, 5 = auto and 6 = powershare.
    • "prio_auto": Whether the priority is automatically determined based on the number of available sources. (boolean, 0 = false, 1 = true)
  • When $command is "searchresult", amule_load_vars returns an array containing the search results of the latest search. The keys and values are:
    • "name": Full name of the file with extension.
    • "short_name": The full name trucated after some chars and ended with three periods.
    • "hash": Unique id of the file, is used for other commands.
    • "size": File size in bytes.
    • "sources": Number of found sources.
    • "present": Whether file is already downloaded/downloading (boolean)
  • When $command is "servers", amule_load_vars returns an array containing the servers currently in the server list. The keys and values are:
    • "name": Name of the server.
    • "desc": Description of the server.
    • "addr": IP-address including port.
    • "users": Number of users connected to the server.
    • "ip": IP-address of the server.
    • "port": Port to use to connect to the server.
    • "maxusers": Maximum number of users allowed on the server.
    • "files": Number of files indexed by the server.
  • When $command is "stats-graph", amule_load_vars returns images containing graphs of some of the stats. They are ...x... pixels. Their names are ...
    • Download speed, upload speed, ed2k connections, kad connections.
  • When $command is "stats_tree", amule_load_vars returns an array containing the stats
Programming example
$var = amule_load_vars($name_of_variable)
foreach ($var as $i) {
}

amule_get_version

amule_get_version(): Returns version number string.

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.

Retrieved from "http://wiki.amule.org/w/index.php?title=AMuleWeb_PHP&oldid=27569"