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

	XMLRPCtest ($string)
	this is a test function that call be called when getting XML RPC calls to this site to work More...

	XMLRPCgetImages ()
	gets the images to which the user has access More...

	XMLRPCaddRequest ($imageid, $start, $length, $foruser='', $nousercheck=0)
	tries to make a request More...

	XMLRPCaddRequestWithEnding ($imageid, $start, $end, $foruser='', $nousercheck=0)
	tries to make a request with the specified ending time More...

	XMLRPCdeployServer ($imageid, $start, $end, $admingroup='', $logingroup='', $ipaddr='', $macaddr='', $monitored=0, $foruser='', $name='', $userdata='')
	tries to make a server request More...

	XMLRPCgetRequestIds ()
	gets information about all of user's requests More...

	XMLRPCgetRequestStatus ($requestid)
	determines and returns the status of the request More...

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

	XMLRPCextendRequest ($requestid, $extendtime)
	extends the length of an active request; if a request that has not started needs to be extended, delete the request and submit a new one More...

	XMLRPCsetRequestEnding ($requestid, $end)
	modifies the end time of an active request; if a request that has not started needs to be modifed, delete the request and submit a new one More...

	XMLRPCendRequest ($requestid)
	ends/deletes a request More...

	XMLRPCautoCapture ($requestid)
	creates entries in appropriate tables to capture an image and sets the request state to image More...

	XMLRPCgetGroupImages ($name)
	gets a list of all images in a particular group More...

	XMLRPCaddImageToGroup ($name, $imageid)
	adds an image to a resource group More...

	XMLRPCremoveImageFromGroup ($name, $imageid)
	removes an image from a resource group More...

	XMLRPCaddImageGroupToComputerGroup ($imageGroup, $computerGroup)
	map an image group to a computer group More...

	XMLRPCremoveImageGroupFromComputerGroup ($imageGroup, $computerGroup)
	remove the mapping of an image group to a computer group More...

	XMLRPCgetNodes ($root=NULL)
	gets a list of all nodes in the privilege tree More...

	XMLRPCnodeExists ($nodeName, $parentNode)
	indicates whether a node with that name already exists at this location in the privilege tree More...

	XMLRPCaddNode ($nodeName, $parentNode)
	add a node to the privilege tree as a child of the specified parent node More...

	XMLRPCremoveNode ($nodeID)
	delete a node from the privilege tree More...

	XMLRPCgetUserGroupPrivs ($name, $affiliation, $nodeid)
	get a list of privileges for a user group at a particular node in the privilege tree More...

	XMLRPCaddUserGroupPriv ($name, $affiliation, $nodeid, $permissions)
	add privileges for a user group at a particular node in the privilege tree More...

	XMLRPCremoveUserGroupPriv ($name, $affiliation, $nodeid, $permissions)
	remove privileges for a resource group at a particular node in the privilege tree More...

	XMLRPCgetResourceGroupPrivs ($name, $type, $nodeid)
	get a list of privileges for a resource group at a particular node in the privilege tree More...

	XMLRPCaddResourceGroupPriv ($name, $type, $nodeid, $permissions)
	add privileges for a resource group at a particular node in the privilege tree More...

	XMLRPCremoveResourceGroupPriv ($name, $type, $nodeid, $permissions)
	remove privileges for a resource group from a node in the privilege tree More...

	XMLRPCgetUserGroups ($groupType=0, $affiliationid=0)
	builds a list of user groups More...

	XMLRPCgetUserGroupAttributes ($name, $affiliation)
	gets information about a user group More...

	XMLRPCaddUserGroup ($name, $affiliation, $owner, $managingGroup, $initialMaxTime, $totalMaxTime, $maxExtendTime, $custom=1)
	creates a new user group with the specified parameters More...

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

	XMLRPCremoveUserGroup ($name, $affiliation)
	removes a user group along with all of its privileges More...

	XMLRPCdeleteUserGroup ($name, $affiliation)
	alias for XMLRPCremoveUserGroup More...

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

	XMLRPCaddUsersToGroup ($name, $affiliation, $users)
	adds users to a group More...

	XMLRPCremoveUsersFromGroup ($name, $affiliation, $users)
	removes users from a group More...

	XMLRPCgetResourceGroups ($type)
	get a list of resource groups of a particular type More...

	XMLRPCaddResourceGroup ($name, $managingGroup, $type)
	add a resource group More...

	XMLRPCremoveResourceGroup ($name, $type)
	remove a resource group More...

	XMLRPCblockAllocation ($imageid, $start, $end, $numMachines, $usergroupid, $ignoreprivileges=0)
	creates and processes a block allocation according to the passed in criteria More...

	XMLRPCprocessBlockTime ($blockTimesid, $ignoreprivileges=0)
	processes a block allocation for the blockTimes entry associated with blockTimesid More...

	XMLRPCfinishBaseImageCapture ($ownerid, $resourceid, $virtual =1)
	calls addImagePermissions to create and set up permissions, groupings, and mappings so that the owner of a new base image will be able to make a reservation for it after capturing it using 'vcld -setup'; specifically designed to be called by vcld as part of the process of capturing a new base image More...

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.

Function Documentation

XMLRPCaddImageGroupToComputerGroup	(	$imageGroup,
		$computerGroup
	)

map an image group to a computer group

Parameters

$imageGroup	- the name of an imageGroup
$computerGroup	- the name of a computerGroup

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 - successfully mapped an image group to a computer group

XMLRPCaddImageToGroup	(	$name,
		$imageid
	)

adds an image to a resource group

Parameters

$name	- the name of an imageGroup
$imageid	- the id of an image

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 - image was added to the group

XMLRPCaddNode	(	$nodeName,
		$parentNode
	)

add a node to the privilege tree as a child of the specified parent node

Parameters

$nodeName	- the name of the new node
$parentNode	- the ID of the node parent

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 - node was successfully added

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

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
$nousercheck	- (optional, default=0) set to 1 to disable timeout when user is disconnected for too long

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

XMLRPCaddRequestWithEnding	(	$imageid,
		$start,
		$end,
		$foruser = `''`,
		$nousercheck = `0`
	)

tries to make a request with the specified ending time

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
$end	- unix timestamp for end of reservation; will be rounded up to the nearest 15 minute increment
$foruser	- (optional) login to be used when setting up the account on the reserved machine - CURRENTLY, THIS IS UNSUPPORTED
$nousercheck	- (optional, default=0) set to 1 to disable timeout when user is disconnected for too long

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

XMLRPCaddResourceGroup	(	$name,
		$managingGroup,
		$type
	)

add a resource group

Parameters

$name	- the name of the resource group
$managingGroup	- the name of the managing group
$type	- the type of resource 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 - the resource group was added

XMLRPCaddResourceGroupPriv	(	$name,
		$type,
		$nodeid,
		$permissions
	)

add privileges for a resource group at a particular node in the privilege tree

Parameters

$name	- the name of the resource group
$type	- the resource group type
$nodeid	- the ID of the node in the privilege tree
$permissions	- a colon (:) delimited list of privileges to add

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 - privileges were successfully added

XMLRPCaddUserGroup	(	$name,
		$affiliation,
		$owner,
		$managingGroup,
		$initialMaxTime,
		$totalMaxTime,
		$maxExtendTime,
		$custom = `1`
	)

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
$custom	- (optional, default=1) set custom flag for user group; if set to 0, $owner and $managingGroup will be ignored and group membership will be managed via authentication protocol

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

XMLRPCaddUserGroupPriv	(	$name,
		$affiliation,
		$nodeid,
		$permissions
	)

add privileges for a user group at a particular node in the privilege tree

Parameters

$name	- the name of the user group
$affiliation	- the affiliation of the user group
$nodeid	- the ID of the node in the privilege tree
$permissions	- a colon (:) delimited list of privileges to add

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 - privileges were successfully added

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

XMLRPCautoCapture ( $requestid )

creates entries in appropriate tables to capture an image and sets the request state to image

Parameters

$requestid - id of request to be captured

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 - image was successfully set to be captured

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

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

Parameters

$imageid	- id of the image to be used
$start	- mysql datetime for the start time (i.e. machines should be prep'd and ready by this time)
$end	- mysql datetime for the end time
$numMachines	- 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 allocation 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 allocations that have been processed
unallocated - total number of desired allocations that have not been processed
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 allocations that have been processed
unallocated - total number of desired allocations that have not been processed

NOTE: 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
	)

alias for XMLRPCremoveUserGroup

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 removed

XMLRPCdeployServer	(	$imageid,
		$start,
		$end,
		$admingroup = `''`,
		$logingroup = `''`,
		$ipaddr = `''`,
		$macaddr = `''`,
		$monitored = `0`,
		$foruser = `''`,
		$name = `''`,
		$userdata = `''`
	)

tries to make a server 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
$end	- "indefinite" or unix timestamp for end of reservation; will use a floor function to round up to the nearest 15 minute increment for actual reservation
$admingroup	- (optional, default='') admin user group for reservation
$logingroup	- (optional, default='') login user group for reservation
$ipaddr	- (optional, default='') IP address to use for public IP of server
$macaddr	- (optional, default='') MAC address to use for public NIC of server
$monitored	- (optional, default=0) whether or not the server should be monitored - CURRENTLY, THIS IS UNSUPPORTED
$foruser	- (optional) login to be used when setting up the account on the reserved machine - CURRENTLY, THIS IS UNSUPPORTED
$name	- (optional) name for reservation
$userdata	- (optional) text that will be placed in /root/.vclcontrol/post_reserve_userdata on the reserved node

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

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

XMLRPCextendRequest	(	$requestid,
		$extendtime
	)

extends the length of an active request; if a request that has not started needs to be extended, delete the request and submit a new one

Parameters

$requestid	- id of a request
$extendtime	- time in minutes to extend reservation

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 extended

XMLRPCfinishBaseImageCapture	(	$ownerid,
		$resourceid,
		$virtual = `1`
	)

calls addImagePermissions to create and set up permissions, groupings, and mappings so that the owner of a new base image will be able to make a reservation for it after capturing it using 'vcld -setup'; specifically designed to be called by vcld as part of the process of capturing a new base image

Parameters

$ownerid	- id of owner of image
$resourceid	- id from resource table for the image
$virtual	- (bool) 0 if bare metal image, 1 if virtual

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 - the permissions, groupings, and mappings were set up successfully

XMLRPCgetGroupImages ( $name )

gets a list of all images in a particular group

Parameters

$name - the name of an imageGroup

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 - returns an array of images; there will be an additional element in the array with an index of 'images' that is an array of images with each element having the following two keys:
id - id of the image
name - name of the image

XMLRPCgetImages ( )

gets the images to which the user has access

Returns: an array of image arrays, each with these indices:
id - id of the image
name - name of the image
description - description of image
usage - usage instructions for image

XMLRPCgetNodes ( $root = NULL )

gets a list of all nodes in the privilege tree

Parameters

$root - (optional, default=top of tree) the ID of the node forming the root of the hierarchy

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 - returns an array of nodes; there will be an additional element in the array with an index of 'nodes' that is an array of nodes with each element having the following three keys:
id - id of the node
name - name of the node
parent - id of the parent node

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 found; 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
OS - name of OS used in image
isserver - 0 or 1 - whether or not this is a server reservation
state - current state of reservation
servername - only included if isserver == 1 - name of the reservation

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

XMLRPCgetResourceGroupPrivs	(	$name,
		$type,
		$nodeid
	)

get a list of privileges for a resource group at a particular node in the privilege tree

Parameters

$name	- the name of the resource group
$type	- the resource group type
$nodeid	- the ID of the node in 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
success - an additional element is returned:
privileges - array of privileges assigned at the node

XMLRPCgetResourceGroups ( $type )

get a list of resource groups of a particular type

Parameters

$type - the resource group type

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 - a 'groups' element will contain an array of groups of the given type

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 six 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
overlapResCount - maximum allowed number of overlapping reservations allowed for users in this group

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

XMLRPCgetUserGroupPrivs	(	$name,
		$affiliation,
		$nodeid
	)

get a list of privileges for a user group at a particular node in the privilege tree

Parameters

$name	- the name of the user group
$affiliation	- the affiliation of the group
$nodeid	- the ID of the node in 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
success - an additional element is returned:
privileges - array of privileges assigned at the node

XMLRPCgetUserGroups	(	$groupType = `0`,
		$affiliationid = `0`
	)

builds a list of user groups

Parameters

$groupType	- (optional, default=0) specify 0 for all groups, 1 for only custom groups, 2 for only courseroll groups
$affiliationid	- (optional, default=0) specifiy an affiliationid to limit returned groups to only those matching the affiliation; pass 0 for all affiliations

Returns

an array with two indices, one named 'status' which will have a value of 'success', the other named 'groups' which will be an array of arrays, each one having the following keys:

id
name
groupaffiliation
groupaffiliationid
ownerid
owner
affiliation
editgroupid
editgroup
editgroupaffiliationid
editgroupaffiliation
custom
courseroll
initialmaxtime
maxextendtime
overlapResCount

XMLRPCnodeExists	(	$nodeName,
		$parentNode
	)

indicates whether a node with that name already exists at this location in the privilege tree

Parameters

$nodeName	- the name of a node
$parentNode	- the ID of the parent node

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 - returns an 'exists' element set to either 1 or 0

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

processes a block allocation 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 allocation 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 allocations that have been processed
unallocated - total number of desired allocations that have not been processed
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 allocations that have been processed
unallocated - total number of desired allocations that have not been processed

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

XMLRPCremoveImageFromGroup	(	$name,
		$imageid
	)

removes an image from a resource group

Parameters

$name	- the name of an imageGroup
$imageid	- the id of an image

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 - image was removed from the group

XMLRPCremoveImageGroupFromComputerGroup	(	$imageGroup,
		$computerGroup
	)

remove the mapping of an image group to a computer group

Parameters

$imageGroup	- the name of an imageGroup
$computerGroup	- the name of a computerGroup

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 - successfully removed the mapping from an image group to a computer group

XMLRPCremoveNode ( $nodeID )

delete a node from the privilege tree

Parameters

$nodeID - the ID of a node

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 - node was successfully deleted

XMLRPCremoveResourceGroup	(	$name,
		$type
	)

remove a resource group

Parameters

$name	- the name of the resource group
$type	- the resource group type

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 - the resource group was removed

XMLRPCremoveResourceGroupPriv	(	$name,
		$type,
		$nodeid,
		$permissions
	)

remove privileges for a resource group from a node in the privilege tree

Parameters

$name	- the name of the resource group
$type	- the resource type
$nodeid	- the ID of the node in the privilege tree
$permissions	- a colon (:) delimited list of privileges to remove

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 - privileges were successfully removed

XMLRPCremoveUserGroup	(	$name,
		$affiliation
	)

removes 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 removed

XMLRPCremoveUserGroupPriv	(	$name,
		$affiliation,
		$nodeid,
		$permissions
	)

remove privileges for a resource group at a particular node in the privilege tree

Parameters

$name	- the name of the user group
$affiliation	- the affiliation of the user group
$nodeid	- the ID of the node in the privilege tree
$permissions	- a colon (:) delimited list of privileges to remove

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 - privileges were successfully removed

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

XMLRPCsetRequestEnding	(	$requestid,
		$end
	)

modifies the end time of an active request; if a request that has not started needs to be modifed, delete the request and submit a new one

Parameters

$requestid	- id of a request
$end	- unix timestamp for end of reservation; will be rounded up to the nearest 15 minute increment

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 extended

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)

Functions

Detailed Description

API Version 2

Function Documentation