Understanding Event-Handlers

<< Click to Display Table of Contents >>

Navigation:  Handling Events via Scripting >

Understanding Event-Handlers

Event handlers are reactions to events that occur during a FTP(S) or a SSH/SFTP session. They take place inside the actual thread that is handling the connection and they are "synchronous" to the calling thread; it means that the Syncplify.me Server! will not return a result code to the client (which is waiting for it) until the scripts you have specified to handle a certain event have completed their execution.


It is very important to understand the concept of synchronicity of Syncplify.me Server! event handlers because, for instance, if you write a script that will compress (zip) a file and you set it to be run by the "after a file is uploaded" event-handler, the server will not return a result code to the client until the file has been compressed. Therefore, if the client has uploaded a very large file (maybe several GB) the compression operation may take very long to complete, and this may cause a timeout on the client side, which wouldn't receive the server response in a timely fashion and eventually drop the connection.


So, when you write scripts to handle events in Syncplify.me Server!, please, always take performance into account. For example, check the file size before compressing (or emailing) it and decide whether to compress (or email) it or not based upon such information.


Anyway, it must be said that most Syncplify.me Server! functions return in a matter of milliseconds, or even microseconds. Functions that might take a long time to execute are clearly documented in this help file.


Furthermore you have to keep in mind that not all Syncplify.me Server! objects are always available in all scripts. The availability of a certain objects is not related to the script itself, but to the event handler to which the script is associated. For instance, the ObjectName/VirtualObjectName variables are only available in scripts executed by file-related or directory-related event handlers. So the ObjectName variable will contain the actual file name that was uploaded if the script is executed by the "after a file has been uploaded" event handler, but it will be empty if the script (even the same script) is executed by the "before opening a shell" even handler.


For each Syncplify.me Server! object you will find in this help file a specification about "when" (in which event handler) such object is available.


Our recommendation: before writing a script, please, always have clear in your mind which event handler will execute the script you're going to write. This will prevent many mistakes and make development a lot easier. Thank you.


You can read more (and access examples) about scripting on our Knowledge Base web site.