CVMWebAPI.js Reference

1. Getting Started
2. API Overview
   • Global Methods
   • Plugin Methods
   • Session Methods
   • Session Properties

The CVMWebAPI.js library provides a high-level interface to the CernVM Web API plugin. It takes care most of the demanding operations, letting you enjoy only the useful functionality.

Getting Started

First thing you should do after you include the library is to request API Access using the CVM.startCVMWebAPI() function:

<script type="text/javascript" src="http://labs.wavesoft.gr/micro/js/cvmwebapi-1.0.js"></script>
<script type="text/javascript">

// Start CernVM Web API
CVM.startCVMWebAPI(
   function(plugin) {
   }
);

</script>

The the successCallback is called after the plugin is instantiated and initialised. The first argument is a WebAPIPlugin object. Using this object you can request the creation of a session using the requestSession function:

function(plugin) {
   plugin.requestSession("http://example.com/vmcp.cgi?vm=33123", function(session) {
      // Now you can use your session in the 'session' variable.
   }
}

This function will either resume a previous instance of the given session or create a new one. In both cases, the configuration is obtained from the VMCP endpoint. You can check the VMCP Reference for more details on this topic.

API Overview

Global Methods

The following methods are exposed under the CVM namespace.

void startCVMWebAPI

( function( pluginInstance ) successCallback, function( message, code ) failureCallback (Optional) )

Initialise CernVM WebAPI application and connect to it. This function performs a lot of heavy-lifting for the user. In detail, it tries to perform the following tasks in sequence: Try to contact CernVM WebAPI Through it's websocket. Try to launch it through `cernvm-webapi:` url handler. If nothing happens a timeout occurs and the user is prompted to install the plug-in. The library will keep polling until a connection becomes available. Send handshake to the application and initiate context. Call back to the user. </td>

Plugin Methods

The following methods are exposed under the CVM.WebAPIPlugin class:

bool stopService	( )
Shut down the CernVM WebAPI Process. This function is available only when you are interfacing the plug-in from a privileged domain (handshake with an authorization token). </td>
void requestSession	( string configURL, function( session ) successCallback, function( message, code ) failureCallback )
request a new (or resume an existing) session. The library will take care of prompting the user accordingly and when a session is open it will fire the successCallback function.
void addEventListener	( string eventName, function( ... ) eventHandler )
Register a function that will be called when the given event is fired.
void removeEventListener	( string eventName, function( ... ) eventHandler )
Unregister an event handler previously registered with the addEventListener function.

Plugin Events

The following events are fired from the CVM.WebAPIPlugin class:

started	( String progressMessage )
This event is fired when a lengthy process is about to start.
completed	( String progressMessage )
This event is fired when a lengthy process has completed.
progress	( String progressMessage, float progressPosition )
This event is fired when during a lengthy process. The first argument is the name of the task being performed. The second one is a number between 0.0 (not started) and 1.0 (completed).
error	( String errorMessage )
This event is fired when an error occurs.

Session Methods

The following methods are exposed under the CVM.WebAPISession class:

bool start	( Object macroValues = { } )
Boot the virtual machine if it's powered off, or resume it if it's pasued or hibernated. The macroValues parameter is a javascript object which contains the names and the values of the possible template variables that exist in the userData script. Consult the VMCP Reference for more details.
bool stop	( )
Stop the Virtual Machine.
bool pause	( )
Pause the Virtual Machine.
bool resume	( )
Resume the Virtual Machine.
bool hibernate	( )
Save the Virtual Machine on disk.
bool reset	( )
Issue a forced reboot to the Virtual Machine.
bool close	( )
Close the session by removing it's hypervisor reflection. This action performs a complete cleanup in the session but keeps the configuration.

Session Events

The following events are fired from the CVM.WebAPISession class:

started	( String progressMessage )
This event is fired when a lengthy process is about to start.
completed	( String progressMessage )
This event is fired when a lengthy process has completed.
progress	( String progressMessage, float progressPosition )
This event is fired when during a lengthy process. The first argument is the name of the task being performed. The second one is a number between 0.0 (not started) and 1.0 (completed).
error	( String errorMessage )
This event is fired when an error occurs.
stateChanged	( int stateCode )
This event is fired when the virtual machine changes state (ex. powered off, started, paused).
resolutionChanged	( int width, int height, int colorDepth )
This event is fired when the virtual machine changes it's screen resolution. This event is useful when you implement your own RDP window and you want to resize it dynamically.
apiStateChanged	( bool isAPIAvailable, String apiURL )
This event is fired when the designated API port becomes available or unavailable. The second parameter is the URL the javascript library should contact.

Session Properties

The following properties are exposed under the CVM.WebAPISession class:

(read-only)	int	state
The current (numeric) state of the session.
(read-only)	string	stateName
The current human-readable state of the session.
(read-only)	string	ip
The IP address of the running VM.
(read-only)	int	ram
The ammount of RAM allocated to the VM.
(read-only)	int	disk
The amount of disk allocated to he new VM.
(read-only)	string	version
The CernVM version used in this session.
(read-only)	string	flavor
The CernVM Flavor used in this session.
(read-only)	string	diskURL
The disk URL of the manually-specified disk used by the webapi.
(read-only)	string	apiURL
The API URL to contact in order to interface with the Virtual Machine.
(read-only)	string	rdpURL
The RDP url to contact in order to display the VM screen.
(writable)	SessionFlags	flags
The flags .
(writable)	int	executionCap
The execution cap to set to the new (or running) session. This value is expressed in percentage.