It's Magic! No, just kidding. This is pure Unix technology taken from the 70s ported to a powerful messaging client. If you know what Git hooks, Nagios checks/plugins or CGI scripts are, then you already know what Smuxi hooks are, if you don't then continue reading this paragraph. Any executable program in a special location (hook points) will be executed when a specific event happens, like receiving a message. This program gets all information passed as environment variables, like who send the message (SENDER), what was the message (MSG), when was it received (MSG_TIMESTAMP_UNIX) etc. This program is also able to execute Smuxi commands by writing hook commands to the standard output.
Currently there are 3 different types of Smuxi hook points:
Smuxi hooks are maintained in the smuxi-hooks git repository. So if you want to share your written hook simply create a pull request against that repository on GitHub, other Smuxi users will be very thankful! Here a list of some already implemented ones:
"Wow, I am completely amazed, but how can I install hooks?" For now you will need to either download the files of the hook into the same location into $HOME/.local/share/smuxi/hooks or by cloning the git repository and symlinking the files. Here is an example for each method:
mkdir -p $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/ cd $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/ wget https://raw.github.com/meebey/smuxi-hooks/master/now-playing/frontend/command-manager/command-np/now-playing.sh chmod +x now-playing.sh
cd $HOME git clone https://github.com/meebey/smuxi-hooks.git mkdir -p $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/ cd $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/ ln -s $HOME/smuxi-hooks/now-playing/frontend/command-manager/command-np/now-playing.sh
Hooks are automatically activated when they are placed in the right location. So after putting them in the hook point location (see see Hook Points section) you don't need to do anything else.
The base location (without the hook point part) is for
All variables are prefixed with SMUXI_ to prevent clash with other environment variables.
Hooks are executed when the event occurs and have to exit so further processing can be done. If hooks need to retain state they can write their state to files of the current directory ($PWD). Each hook has its own state directory and can be found in $HOME/.local/share/smuxi/hook-state/$HOOK_PATH. The hook does not need to change to or create the state directory, as the hook runner will do this for the hook, guaranteed.
This hook point is raised when the presence status of a protocol manager changes. This happens for example when an IRC connection toggles the away state.
Event specific environment variables:
This hook point raises event messages that usually begin with "-!-". This can be useful to track state changes that are shown as a message without having a dedicated hook point for it.
This hook point is raised on the engine side for commands, e.g. /some_command that isn't handled by the frontend or engine built-in commands. This is useful for commands that should be available for all frontends and isn't specific to the frontend environment.
This hook point is raised on the frontend side for commands, e.g. /some_command that isn't handled by the frontend or engine built-in commands. This is useful for commands that rely on the frontend environment, like dealing with windows, notifications, D-Bus, etc.
Supported session commands can be found here.
echo "Session.Command /echo I am a hook!"
Supported protocol manager commands fully depends on the protocol manager implementation/type, thus you need to check the PROTOCOL_MANAGER_PROTOCOL environment variable first! Here you can find a list for IRC, Twitter, XMPP, JabbR and Campfire.
if [ "$SMUXI_PROTOCOL_MANAGER_PROTOCOL" = "IRC" ]; then echo "ProtocolManager.Command /topic This is the new topic" fi