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 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.

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 Properties

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

(read-only)	int	state
(read-only)	string	stateName
(read-only)	string	ip
(read-only)	int	ram
(read-only)	int	disk
(read-only)	string	version
(read-only)	string	flavor
(read-only)	string	diskURL
(read-only)	string	apiURL
(read-only)	string	rdpURL
(writable)	SessionFlags	flags
(writable)	int	executionCap