nodejs-bindings overview

                                    README
                                   ========

This directory contains node.js bindings for libgridcentric (the guest tools).
In order to built the extension, you will need to install the gc-guest-base
package for the gc-guest.h header and the presence of libgridcentric.

The initial skeleton and build scripts for this module were derived from the
incredibly useful node.js blog post by cloudkick, available at:
 https://www.cloudkick.com/blog/2010/aug/23/writing-nodejs-native-extensions/

The tests/ directory contains basic tests, which also serve of examples for how
to use the system.  The actual bindings are almost exactly the same as the
native C bindings, with the following exceptions:

Callbacks
---------

Basic non-blocking functions will return their result immediately (gc_version,
gc_check, gc_my_ip, etc.).

The following blocking functions require an additional callback, the normal
return value for the function is returned as a single parameter to the
callback.
 * list_clone_domains
 * list_ticket_domains
 * get_domain_status
 * list_tickets
 * wait_domain
 * wait_any
 * sync_ticket
 * kill_clone_domain
 * killall_clone_domains
 * killall_ticket_domains
 * request_tickets
 * cancel_ticket
 * clone
 * make_ticket_independent

Native structures and lists
---------------------------

The lists normally returned by list_clone_domains, list_ticket_domains,
list_tickets are returned (through the callback) as JavaScript arrays of
objects with the same fields as the native gc_domain_info_t and
gc_ticket_info_t types.

Single objects are returned by wait_domain and wait_any, with the same fields
as the native gc_domain_exit_t type.

Status codes
------------

All status codes (including those embedded in the objects mentioned above) are
converted from integers to their respective string representations in the
JavaScript world.  For example, get_domain_status does not return an integer
status code, instead it returns a string (such as "ONLINE" or "CRASHED").
Integers are still used to represent errors in many cases however, for example,
clone will still generally give a return value that is a vmid -- or a -1 if an
error occured.