Difference between revisions of "Events"

Revision as of 19:19, 9 November 2008

What are Events

Events are actions aMule can take upon when certain things happen. These actions are configured on the Events tab of the Usage_Preferences notebook or, if you are running amuled, in the [UserEvents] section of amule.conf.

There are four kinds of Events supported at the moment:

• Download completed
• New chat session
• Out of space
• Error on completion

When one of these events is triggered, you can configure aMule to execute a

• core command
• GUI command

A core command is a command that will be executed by a flavor of aMule that has a core (aMule daemon or aMule monolithic). A GUI command is a command that will be executed by a flavor of aMule that has GUI (aMule GUI or aMule monolithic). Notice that if you specify both, aMule monolithic will execute both.

Event Types

Download completed

When aMule completes a download, a Download completed event is triggered. The following variables can be accessed:

•  %FILE - the name of the downloaded file with full path
•  %NAME - the name of the downloaded file without path
•  %HASH - the ed2k hash of the downloaded file
•  %SIZE - the size in bytes of the downloaded file
•  %DLACTIVETIME - the total time the download was active

New chat session

When someone initiates a chat session with you, the New chat session event is triggered. When this happens, the following variable can be accessed:

•  %Sender - username of the person initiating the chat

Out of space

When aMule runs out of diskspace on the partition which it uses for its temporary files, the Out of space event is triggered. When this happens, the following variable can be accessed:

•  %PARTITION

Error on completion

When aMule is unable to move a file from the "temporary" directory to the "incoming" directory, an Error on completion event is triggered. This is typically caused by lack of diskspace on the partition where the incoming directory is located. When this happens, the following variable can be accessed:

•  %FILE

Syntax

Event commands can be either a single or compound shell command, or a shell script. In the Core command field, enter the command or script name followed by the optional parameters like this:

MyScript.sh %NAME %FILE %HASH %SIZE "%DLACTIVETIME"

Note: If the filename contains spaces, the variable names should be enclosed in quotes like this:

MyScript.sh "%NAME" "%FILE" %HASH %SIZE "%DLACTIVETIME"

Your shell script can obtain the values in the parameters the customary way, ie, by evaluating $1, $2, $3, etc.

You need to make sure your script is in your PATH or that you supply the full pathname.

Errors

If your script fails to execute for any reason, this will be logged in aMule's logfile

Examples

A simple command might look like this:

echo "aMule error: %PARTITION is full." | mail -s Warning mymail@domain.tld

This inserts the variable %PARTITION in the text of a one-line email message and sends it to the email address specfied.

For more elaborate purposes, you will will want to call an external script.

Here the bash script by Ezeltje from aMule-Forum which will send you an email every time a download is completed. To use it, enter your email address where indicated and save it to a location in your PATH. Then add this line:

doneDL.sh "%NAME" "%FILE" %HASH %SIZE "%DLACTIVETIME"

to the Core command field of the Download completed section of the Events page. It will now be invoked everytime aMule finishes a download.

 #!/bin/bash
 #
 # doneDL.sh - sends an email upon completion of an aMule download
 # Used in conjuction with aMule's Event feature
 #
 # Call like this: doneDL.sh "%NAME" "%FILE" %HASH %SIZE "%DLACTIVETIME"
 #
 # Enter your email address here:
 eMail=
 #
 NameShort=$1
 NameLong=$2
 Hash=$3
 Size=$4
 DLtime=$5
 {
 echo aMule completed this download:
 echo ------------------------------
 echo
 echo File: "$NameLong"
 echo Hash: $Hash
 echo -n "Time: "
 date | awk '{print $4 " " $5}'
 echo -n Size: $Size bytes 
 if [ $Size -gt 102400 ] ; then echo " ("$(($(($Size / 1024)) / 1024)) "Mb)" ; fi
 if [ ! -z "$DLtime" ] ; then echo "Active download time:" $DLtime ; fi
 echo
 echo --------------------------------------------------------------------
 cas
 echo -n "Resident memory: "
 echo $(ps u -C amule --no-headers | awk '{print $6}') kB
 echo -n "Virtual memory:  "
 echo $(ps u -C amule --no-headers | awk '{print $5}') kB
 echo --------------------------------------------------------------------
 } | mail -s "$NameShort" $eMail