xmlrpcWrappers.php File Reference


Functions
	XMLRPCaffiliations ()
	gets all of the affilations for which users can log in to VCL NOTE: This is the only function available for which the X-User and X-Pass HTTP headers do not need to be passed
	XMLRPCgetImages ()
	gets the images to which the user has acces
	XMLRPCaddRequest ($imageid, $start, $length, $foruser='')
	tries to make a request
	XMLRPCgetRequestStatus ($requestid)
	determines and returns the status of the request
	XMLRPCgetRequestConnectData ($requestid, $remoteIP)
	if request is ready, adds the connecting user's computer to the request and returns info about how to connect to the computer
	XMLRPCendRequest ($requestid)
	ends/deletes a request
	XMLRPCgetRequestIds ()
	gets information about all of user's requests
	XMLRPCblockAllocation ($imageid, $start, $end, $requestcount, $usergroupid, $ignoreprivileges=0)
	creates and processes a block reservation according to the passed in criteria
	XMLRPCprocessBlockTime ($blockTimesid, $ignoreprivileges=0)
	processes a block reservation for the blockTimes entry associated with blockTimesid
	XMLRPCaddUserGroup ($name, $affiliation, $owner, $managingGroup, $initialMaxTime, $totalMaxTime, $maxExtendTime)
	creates a new user group with the specified parameters
	XMLRPCgetUserGroupAttributes ($name, $affiliation)
	gets information about a user group
	XMLRPCdeleteUserGroup ($name, $affiliation)
	deletes a user group along with all of its privileges
	XMLRPCeditUserGroup ($name, $affiliation, $newName, $newAffiliation, $newOwner='', $newManagingGroup='', $newInitialMaxTime='', $newTotalMaxTime='', $newMaxExtendTime='')
	modifies attributes of a user group NOTE: an empty string may be passed for any of the new* fields to leave that item unchanged
	XMLRPCgetUserGroupMembers ($name, $affiliation)
	gets members of a user group Note: it is possible to have a group with no members in which case success will be returned with an empty array for members
	XMLRPCaddUsersToGroup ($name, $affiliation, $users)
	adds users to a group
	XMLRPCremoveUsersFromGroup ($name, $affiliation, $users)
	removes users from a group
	XMLRPCtest ($string)
	this is a test function that call be called when getting XML RPC calls to this site to work

Detailed Description

The functions listed here are for making VCL requests from other applications. They are implemented according to the XML RPC spec defined at http://www.xmlrpc.com/
There is one function called XMLRPCtest() that can be used during initial development to get started without actually making a request.

The URL you will use to submit RPC calls is the URL for your VCL site followed by

index.php?mode=xmlrpccall

for example if the URL for your VCL site is

https://vcl.mysite.org/vcl/

the RPC URL would be

https://vcl.mysite.org/vcl/index.php?mode=xmlrpccall

There is one exception - when calling the XMLRPCaffiliations function, the mode is xmlrpcaffiliations, for example:

https://vcl.mysite.org/vcl/index.php?mode=xmlrpcaffiliations

Your application must connect using HTTPS.

Internal to the VCL code, "Reservations" are called "Requests"; therefore, "request" is used instead of "reservation" in this documentation and in the RPC functions.

API Version 2

This is the current version of the API. It should be used for any new code development. Any older code needs to be migrated to this version.

Authentication is handled by 2 additional HTTP headers you will need to send:
X-User - the userid you would use to log in to the VCL site, followed by the at sign (@), followed by your affiliation
example: myuserid@NCSU
You can obtain a list of the affiliations by using the XMLRPCaffiliations() call

X-Pass - the password you would use to log in to the VCL site

There is one other additional HTTP header you must send:
X-APIVERSION - set this to 2

The X-User and X-Pass HTTP headers do not need to be passed to call the XMLRPCaffiliations() function.

API Version 1

NOTICE: API version 1 will probably be removed in VCL 2.2. If you are still using API version 1, you need to update your code to use version 2.

This version is being phased out in favor of version 2. Documentation is provided for those currently using version 1 who are not ready to switch to using version 2.

Authentication is handled by 2 additional HTTP headers you will need to send:
X-User - use the same id you would use to log in to the VCL site
X-Pass - the key mentioned above

There is one other additional HTTP header you must send:
X-APIVERSION - set this to 1

Function Documentation

XMLRPCaddRequest	(	$	imageid,
		$	start,
		$	length,
		$	foruser = `''`
	)

tries to make a request

Parameters:

	$imageid	- id of an image
	$start	- "now" or unix timestamp for start of reservation; will use a floor function to round down to the nearest 15 minute increment for actual reservation
	$length	- length of reservation in minutes (must be in 15 minute increments)
	$foruser	- (optional) login to be used when setting up the account on the reserved machine - CURRENTLY, THIS IS UNSUPPORTED

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

notavailable - no computers were available for the request
success - there will be an additional element in the array:

requestid - identifier that should be passed to later calls when acting on the request

XMLRPCaddUserGroup	(	$	name,
		$	affiliation,
		$	owner,
		$	managingGroup,
		$	initialMaxTime,
		$	totalMaxTime,
		$	maxExtendTime
	)

creates a new user group with the specified parameters

Parameters:

	$name	- name of user group
	$affiliation	- affiliation of user group
	$owner	- user that will be the owner of the group in username@affiliation form
	$managingGroup	- user group that can manage membership of this one
	$initialMaxTime	- (minutes) max initial time users in this group can select for length of reservations
	$totalMaxTime	- (minutes) total length users in the group can have for a reservation (including all extensions)
	$maxExtendTime	- (minutes) max length of time users can request as an extension to a reservation at a time

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - user group was successfully created

/////////////////////////////////////////////////////////////////////////////

XMLRPCaddUsersToGroup	(	$	name,
		$	affiliation,
		$	users
	)

adds users to a group

Parameters:

	$name	- name of user group
	$affiliation	- affiliation of user group
	$users	- array of users in username@affiliation form to be added to the group

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - users successfully added to the group

warning - there was a non-fatal issue that occurred while processing the call; there will be three additional elements in this case:

warningcode - warning number
warningmsg - warning string
failedusers - array of users in username@affiliation form that could not be added

/////////////////////////////////////////////////////////////////////////////

XMLRPCaffiliations ( )

gets all of the affilations for which users can log in to VCL
NOTE: This is the only function available for which the X-User and X-Pass HTTP headers do not need to be passed

Returns:: an array of affiliation arrays, each with 2 indices:
id - id of the affiliation
name - name of the affiliation

XMLRPCblockAllocation	(	$	imageid,
		$	start,
		$	end,
		$	requestcount,
		$	usergroupid,
		$	ignoreprivileges = `0`
	)

creates and processes a block reservation according to the passed in criteria

Parameters:

	$imageid	- id of the image to be used
	$start	- mysql datetime for the start time (i.e. requests should be prep'd and ready by this time)
	$end	- mysql datetime for the end time
	$requestcount	- number of computers to allocate
	$usergroupid	- id of user group for checking user access to machines
	$ignoreprivileges	(optional, default=0) - 0 (false) or 1 (true) - set to 1 to select computers from any that are mapped to be able to run the image; set to 0 to only select computers from ones that are both mapped and that users in the usergroup assigned to this block request have been granted access to through the privilege tree

Returns:

an array with blockTimesid as an index with the value of the newly created block time and at least one other index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - blockTimesid was processed; there will be two additional elements in this case:

allocated - total number of desired requests that have been allocated
unallocated - total number of desired requests that have not been allocated

warning - there was a non-fatal issue that occurred while processing the call; there will be four additional elements in this case:

warningcode - warning number
warningmsg - warning string
allocated - total number of desired requests that have been allocated
unallocated - total number of desired requests that have not been allocated

note that status may be warning, but allocated may be 0 indicating there were no errors that occurred, but there simply were not any machines available

XMLRPCdeleteUserGroup	(	$	name,
		$	affiliation
	)

deletes a user group along with all of its privileges

Parameters:

	$name	- name of user group
	$affiliation	- affiliation of user group

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - user group was successfully deleted

/////////////////////////////////////////////////////////////////////////////

XMLRPCeditUserGroup	(	$	name,
		$	affiliation,
		$	newName,
		$	newAffiliation,
		$	newOwner = `''`,
		$	newManagingGroup = `''`,
		$	newInitialMaxTime = `''`,
		$	newTotalMaxTime = `''`,
		$	newMaxExtendTime = `''`
	)

modifies attributes of a user group
NOTE: an empty string may be passed for any of the new* fields to leave that item unchanged

Parameters:

	$name	- name of user group
	$affiliation	- affiliation of user group
	$newName	- new name for user group
	$newAffiliation	- new affiliation for user group
	$newOwner	- (optional, default='') user that will be the owner of the group in username@affiliation form
	$newManagingGroup	- (optional, default='') user group that can manage membership of this one
	$newInitialMaxTime	- (optional, default='') (minutes) max initial time users in this group can select for length of reservations
	$newTotalMaxTime	- (optional, default='') (minutes) total length users in the group can have for a reservation (including all extensions)
	$newMaxExtendTime	- (optional, default='') (minutes) max length of time users can request as an extension to a reservation at a time

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - user group was successfully updated

/////////////////////////////////////////////////////////////////////////////

XMLRPCendRequest ( $ requestid )

ends/deletes a request

Parameters:

$requestid

- id of a request

Returns:

an array with at least one index named 'status' which will have one of these values
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - request was successfully ended

XMLRPCgetImages ( )

gets the images to which the user has acces

Returns:: an array of image arrays, each with 2 indices:
id - id of the image
name - name of the image

XMLRPCgetRequestConnectData	(	$	requestid,
		$	remoteIP
	)

if request is ready, adds the connecting user's computer to the request and returns info about how to connect to the computer

Parameters:

	$requestid	- id of a request
	$remoteIP	- ip address of connecting user's computer

Returns:

an array with at least one index named 'status' which will have one of these values
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

ready - request is ready; there will be 3 additional elements in the array:

serverIP - address of the reserved machine
user - user to use when connecting to the machine
password - password to use when connecting to the machine

notready - request is not ready for connection

XMLRPCgetRequestIds ( )

gets information about all of user's requests

Returns:

an array with at least one index named 'status' which will have one of these values
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - request was successfully ended; there will be an additional element whose index is 'requests' which is an array of arrays, each having these elements (or empty if no existing requests):

requestid - id of the request
imageid - id of the image
imagename - name of the image
start - unix timestamp of start time
end - unix timestamp of end time

XMLRPCgetRequestStatus ( $ requestid )

determines and returns the status of the request

Parameters:

$requestid

- id of a request

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

ready - request is ready
failed - request failed to load properly
timedout - request timed out (user didn't connect before timeout expired)
loading - request is still loading; there will be an additional element in the array:

time - the estimated wait time (in minutes) for loading to complete

future - start time of request is in the future

XMLRPCgetUserGroupAttributes	(	$	name,
		$	affiliation
	)

gets information about a user group

Parameters:

	$name	- name of user group
	$affiliation	- affiliation of user group

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - there will be five additional elements in this case:

owner - user that will be the owner of the group in username@affiliation form
managingGroup - user group that can manage membership of this one in groupname@affiliation form
initialMaxTime - (minutes) max initial time users in this group can select for length of reservations
totalMaxTime - (minutes) total length users in the group can have for a reservation (including all extensions)
maxExtendTime - (minutes) max length of time users can request as an extension to a reservation at a time

/////////////////////////////////////////////////////////////////////////////

XMLRPCgetUserGroupMembers	(	$	name,
		$	affiliation
	)

gets members of a user group
Note: it is possible to have a group with no members in which case success will be returned with an empty array for members

Parameters:

	$name	- name of user group
	$affiliation	- affiliation of user group

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - there will be one additional element in this case:

members - array of members of the group in username@affiliation form

/////////////////////////////////////////////////////////////////////////////

XMLRPCprocessBlockTime	(	$	blockTimesid,
		$	ignoreprivileges = `0`
	)

processes a block reservation for the blockTimes entry associated with blockTimesid

Parameters:

	$blockTimesid	- id from the blockTimes table
	$ignoreprivileges	(optional, default=0) - 0 (false) or 1 (true) - set to 1 to select computers from any that are mapped to be able to run the image; set to 0 to only select computers from ones that are both mapped and that users in the usergroup assigned to this block request have been granted access to through the privilege tree

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

completed - blockTimesid was previously successfully processed
success - blockTimesid was processed; there will be two additional elements in this case:

allocated - total number of desired requests that have been allocated
unallocated - total number of desired requests that have not been allocated

warning - there was a non-fatal issue that occurred while processing the call; there will be four additional elements in this case:

warningcode - warning number
warningmsg - warning string
allocated - total number of desired requests that have been allocated
unallocated - total number of desired requests that have not been allocated

note that status may be warning, but allocated may be 0 indicating there were no errors that occurred, but there simply were not any machines available

XMLRPCremoveUsersFromGroup	(	$	name,
		$	affiliation,
		$	users
	)

removes users from a group

Parameters:

	$name	- name of user group
	$affiliation	- affiliation of user group
	$users	- array of users in username@affiliation form to be removed from the group

Returns:

an array with at least one index named 'status' which will have one of these values:
error - error occurred; there will be 2 additional elements in the array:

errorcode - error number
errormsg - error string

success - users successfully removed from the group

warning - there was a non-fatal issue that occurred while processing the call; there will be three additional elements in this case:

warningcode - warning number
warningmsg - warning string
failedusers - array of users in username@affiliation form that could not be removed

/////////////////////////////////////////////////////////////////////////////

XMLRPCtest ( $ string )

this is a test function that call be called when getting XML RPC calls to this site to work

Parameters:

$string

- a string

Returns:: an array with 3 indices:
status - will be 'success'
message - will be 'RPC call worked successfully'
string - contents of $string (after being sanatized)

xmlrpcWrappers.php File Reference

Functions

Detailed Description

API Version 2

API Version 1

Function Documentation