######################################################### # # # BUGGER Auto Install Functionality # # Client Implementation API # # # # Document Date: 27 March 2010 # # # # Document Author: Ben Tasker # # # ######################################################### Contents --------- - System Requests - System Responses - Install Complete - Error Responses System Requests ---------------- Requests for the Auto Install API should be made to /BUGGER/AutoInstall.shtml The script expects several variables to be defined in the Request URI. These are; Request Type: TYPE Project ID: PROJ Return Test Releases: TESTING Request Type should be set to Install (note the capital 'I'), to notify the script that we want to run an autoinstall. Project ID should be the project ID as configured in your BUGGER system (usually a number) Return Test Releases specifies whether or not you want to install the unstable version. If you do want an unstable version you should set TESTING to Y (case is important) An example call would be; http://mywebserver.com/BUGGER/AutoInstall.shtml?TYPE=Install&PROJ=1&TESTING=N System Responses ----------------- The system will respond in text format. There will be a single variable per line (Note: if you view the page in a webbrowser, the variables may share a single line) The variables returned are as follows; TARBALL_LOCATION - A URL from which you should download the tarball INSTALL_SCRIPT - A URL allowing you to install the install script ALLOW_CUSTOM_INSTALLS - An indicator showing whether to allow custom install methods (ignore N at your peril!) TESTING_VERSION - An indicator to show whether this is a stable/Unstable version (Y= Unstable N= Stable) TARBALL_CHECKSUM - A MD5 Checksum of the tarball at TARBALL_LOCATION PROJECT_VERSION - Version of the program you will be installing LICENSE - License the program is released under It is very important that you abide by the indicator ALLOW_CUSTOM_INSTALLS. If this is set to Y, you can either run the Installs script at INSTALL_SCRIPT, or your script can use a custom install method (for example to install the program in a specific location.) If this indicator is set to N then it is likely that the program depends on itself being installed in a specific location. You should not ignore this indicator unless you know exactly what you are doing (keep in mind you may need to update your script whenever the project is updated) If TESTING was set to N when you placed your request, TESTING_VERSION will not equal Y. However if you did request an unstable version, this could equal Y or N. If you requested a testing version and one wasn't available the system may return the stable version. Alternatively, it may simply return a null output. LICENSE will be the license identifier used by BUGGER, you are advised to use this to retrieve and display a copy of the project's license for the user to agree to before the install commences. An API for this task will be published soon. Install Complete ----------------- Once your program has retrieved and installed the project, you are advised to check for updates in case there are incremental updates available. The API for the Update function is similar to the Autoinstall and can be found at http://benscomputer.no-ip.org/BUGGER/ Error Responses ----------------- If the system doesn't recognise the value of TYPE (either because you forgot to supply it, or used an invalid value) the system will return the following ERROR: Unknown value passed for TYPE. (You supplied $REQUEST_TYPE) $REQUEST_TYPE will be substituted for the value you supplied. The system may also return the following (pretty self explanatory) error messages; ERROR: An Invalid Project ID was specified - No matching records found ERROR: An Unspecified Claims_DB Error Occurred Your program needs to check for these, there's very little the end user can do to resolve these issues, but they may wish to alert the server admin. You could also write a function to lookup the project ID on the BUGGER server as it's possible someone may have changed it without an understanding of the potential consequences. ######################################################### # # # DOCUMENT END # # Copyright 2010 Ben Tasker # # # # Released under GNU GPL V3 # # See http://benscomputer.no-ip.org # # # #########################################################