Events

From AMule Project FAQ
Revision as of 13:39, 3 October 2017 by Raffe1234 (Talk | contribs | merge | delete)

Jump to: navigation, search

English | Deutsch | Low-Saxon

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

Linux

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

If you want to use sendmail, you can use something like this 

 #!/bin/bash -e
 #
 # aMuleMail.sh - sends an email upon completion of an aMule download
 # Used in conjuction with aMule's Event feature
 #
 # Original script by Ezeltje
 # 
 # Further development by raffe
 # Version 1.1 Changelog 
 # - Use sendmail to send email
 # - Using HTML email format to make text look nice
 # - Move of the citation mark for $DLtime to get "hours" or "minutes" text
 # - Added more info about the system, like uptime, user status, disk usage, 
 #   aMule processes, top processes, route info, IP numbers, gateways, DNS
 #   servers and Iptables
 #
 # Call like this: aMuleMail.sh "%NAME" "%FILE" %HASH %SIZE "%DLACTIVETIME"
 #
 # Lets wait 1 second...
 sleep 1
 #
 NameShort=$1
 NameLong=$2
 Hash=$3
 Size=$4
 DLtime=$5
 {
 # If you need to use a from address
 #echo From: aMule@myurl.com
 # ====> Enter your email address here: ====>
 echo To: youremail@address.com
 echo Subject: "$NameShort"
 echo " "
 # Mail header
 echo "MIME-Version: 1.0"
 echo "Content-Type: text/html"
 echo "Content-Disposition: inline"
 echo "<html>"
 echo "<body>"
echo "
"
  # Mail body
  echo aMule completed this download:
  echo ------------------------------
  echo " "
  echo File: "$NameShort"
  echo Location: "$NameLong"
  echo Hash: $Hash
  echo -n "Date & time: "
  date
  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 "--------------------------------------------------------------------"
  echo "-==============================-"
  echo "-=======-  NAS status -========-"
  echo "-==============================-"
  echo " "
  echo "=== Uptime:"
  uptime
  echo " "
  echo "=== User status:"
  user_status show_all
  echo " "
  echo "=== Disk usage:"
  df -h
  echo " "
  echo "=== aMule processes:"
  ps | grep 'PID\|aMule'
  echo " "
  echo "=== Top processes:"
  top -n 1
  echo " "
  echo "=== Memory:"
  free
  echo " "
  echo "=== Route:"
  route
  echo " "
  echo "=== IP numbers"
  echo "$(ifconfig | grep inet | sed -r 's/^.{10}//')"
  echo " "
  echo "=== Default gateways"
  route | grep default
  echo " "
  echo "=== DNS serves"
  cat /etc/resolv.conf
  echo " "
  echo "=== Iptables:"
  iptables -S
  echo " "
  echo --------------------------------------------------------------------
  # Mail footer
  echo "
" 
 echo "</body>"
 echo "</html>"
 } | sendmail -t


Here the bash scripts by Shuttle (Talk | contribs) – based on Ezeltje's one – which will send you a notification via NotifyOSD and will play a sound for each event. To use them, you must install libnotify-bin and sox packages and enter your sound path where indicated. Then add these lines: 

doneDL.sh "%NAME" "%FILE" %HASH %SIZE "%DLACTIVETIME"
newMsg.sh "%SENDER"
noDiskSpace.sh "%PARTITION"
errorDL.sh "%FILE"

to the Core command field of each section of the Events page. It will now be invoked everytime aMule triggers an event.

  • doneDL.sh: this script will be called everytime aMule finishes a download. 
#!/bin/bash
#
# doneDL.sh
# Used in conjuction with aMule's Event feature
#
# Call like this: doneDL.sh "%NAME" "%FILE" %HASH %SIZE "%DLACTIVETIME"
#
# Enter your sound path here:
soundPath="/usr/share/sounds/gnome/default/alerts/sonar.ogg"
#
nameShort=$1
nameLong=$2
hash=$3
size=$4
dlTime=$5

/usr/bin/notify-send -i amule "Download completed!" "The download of the file “"$nameShort"” has been completed. Here are the data on it: complete path: $nameLong, size: $size bytes, hash: $hash, active download time: $dlTime, resident memory: "$(ps u -C amule --no-headers | awk '{print $6}')" kB, virtual memory: "$(ps u -C amule --no-headers | awk '{print $5}')" kB." && /usr/bin/play "$soundPath"
  • errorDL.sh: this script will be called everytime aMule fails to complete a download. 
#!/bin/bash
#
# errorDL.sh
# Used in conjuction with aMule's Event feature
#
# Call like this: errorDL.sh "%FILE"
#
# Enter your sound path here:
soundPath="/usr/share/sounds/gnome/default/alerts/sonar.ogg"
#

/usr/bin/notify-send -i amule "Ooops…" "We were unable to complete the downlaod of the file $1." && /usr/bin/play "$soundPath"
  • newMsg.sh: this script will be called everytime a user send you a message. 
#!/bin/bash
#
# newMsg.sh
# Used in conjuction with aMule's Event feature
#
# Call like this: newMsg.sh "%SENDER"
#
# Enter your sound path here:
soundPath="/usr/share/sounds/gnome/default/alerts/sonar.ogg"
#

/usr/bin/notify-send -i amule "New message!" "The user $1 sent you a message." && /usr/bin/play "$soundPath"
  • noDiskSpace.sh: this script will be called everytime a download stops because there is no more disk space available. 
#!/bin/bash
#
# noDiskSpace.sh
# Used in conjuction with aMule's Event feature
#
# Call like this: noDiskSpace.sh "%PARTITION"
#
# Enter your sound path here:
soundPath="/usr/share/sounds/gnome/default/alerts/sonar.ogg"
#

/usr/bin/notify-send -i amule "No disk space available!" "The partition $1 does not contain more than enough space to complete the list of downlaods. You must make room if you want to continue downloading with aMule…" && /usr/bin/play "$soundPath"

Windows

A simple setup for Windows users, Running more than one computer as a network, would be... Check the box labeled - Enable command execution on GUI in your amule prefs/Events. Type in the command - net send ComputerName %NAME has finished downloading. Where ComputerName is the name of the computer on your LAN, That you want this message sent to. It can also be the same computer that amule is running on.

Now go into your control panel. Open administrative tools. Open Services. Find the alerter service on the services list, Right click it, and change it to automatic. Also Click the start button, to enable it immediately. Find the messenger service, right click it, change it to automatic, select the start button. This enables windows built in messaging on your computer, It is turned off by default. YOU MUST DO THIS TO EVERY COMPUTER YOU WANT TO USE FOR MESSAGES.

Now when a file is finished downloading in amule. You will get a nice little popup box, that tells you "Amule.text has finished downloading", Or whatever filename it is. And it has an OK button on it to push, to make it go away. This way you will always be notified, when a file is completed.

Now if you prefer to have a voice announce when a file is completed. Get yourself a screen reader program, Such as Thunder, which is completely free. At screenreader.net. Now when your popup announcement is triggered. The screenreader program will read it to you, Using Microsoft Sam, Or some other voice, if you install it. Personally I prefer the neospeech Kate, And Paul voices.

Retrieved from "http://wiki.amule.org/t/index.php?title=Events&oldid=28745"