VCL XML RPC
Functions
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
 XMLRPCtest ($string)
 this is a test function that call be called when getting XML RPC calls to this site to work
 XMLRPCgetImages ()
 gets the images to which the user has access
 XMLRPCaddRequest ($imageid, $start, $length, $foruser='')
 tries to make a request
 XMLRPCaddRequestWithEnding ($imageid, $start, $end, $foruser='')
 tries to make a request with the specified ending time
 XMLRPCdeployServer ($imageid, $start, $end, $admingroup='', $logingroup='', $ipaddr='', $macaddr='', $monitored=0, $foruser='', $name='')
 tries to make a server request
 XMLRPCgetRequestIds ()
 gets information about all of user's requests
 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
 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
 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
 XMLRPCendRequest ($requestid)
 ends/deletes a request
 XMLRPCautoCapture ($requestid)
 creates entries in appropriate tables to capture an image and sets the request state to image
 XMLRPCgetGroupImages ($name)
 gets a list of all images in a particular group
 XMLRPCaddImageToGroup ($name, $imageid)
 adds an image to a resource group
 XMLRPCremoveImageFromGroup ($name, $imageid)
 removes an image from a resource group
 XMLRPCaddImageGroupToComputerGroup ($imageGroup, $computerGroup)
 map an image group to a computer group
 XMLRPCremoveImageGroupFromComputerGroup ($imageGroup, $computerGroup)
 remove the mapping of an image group to a computer group
 XMLRPCgetNodes ($root=NULL)
 gets a list of all nodes in the privilege tree
 XMLRPCnodeExists ($nodeName, $parentNode)
 indicates whether a node with that name already exists at this location in the privilege tree
 XMLRPCaddNode ($nodeName, $parentNode)
 add a node to the privilege tree as a child of the specified parent node
 XMLRPCremoveNode ($nodeID)
 delete a node from the privilege tree
 XMLRPCgetUserGroupPrivs ($name, $affiliation, $nodeid)
 get a list of privileges for a user group at a particular node in the privilege tree
 XMLRPCaddUserGroupPriv ($name, $affiliation, $nodeid, $permissions)
 add privileges for a user group at a particular node in the privilege tree
 XMLRPCremoveUserGroupPriv ($name, $affiliation, $nodeid, $permissions)
 remove privileges for a resource group at a particular node in the privilege tree
 XMLRPCgetResourceGroupPrivs ($name, $type, $nodeid)
 get a list of privileges for a resource group at a particular node in the privilege tree
 XMLRPCaddResourceGroupPriv ($name, $type, $nodeid, $permissions)
 add privileges for a resource group at a particular node in the privilege tree
 XMLRPCremoveResourceGroupPriv ($name, $type, $nodeid, $permissions)
 remove privileges for a resource group from a node in the privilege tree
 XMLRPCgetUserGroups ($groupType=0, $affiliationid=0)
 builds a list of user groups
 XMLRPCgetUserGroupAttributes ($name, $affiliation)
 gets information about a user group
 XMLRPCaddUserGroup ($name, $affiliation, $owner, $managingGroup, $initialMaxTime, $totalMaxTime, $maxExtendTime, $custom=1)
 creates a new user group with the specified parameters
 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
 XMLRPCremoveUserGroup ($name, $affiliation)
 removes a user group along with all of its privileges
 XMLRPCdeleteUserGroup ($name, $affiliation)
 alias for XMLRPCremoveUserGroup
 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
 XMLRPCgetResourceGroups ($type)
 get a list of resource groups of a particular type
 XMLRPCaddResourceGroup ($name, $managingGroup, $type)
 add a resource group
 XMLRPCremoveResourceGroup ($name, $type)
 remove a resource group
 XMLRPCblockAllocation ($imageid, $start, $end, $numMachines, $usergroupid, $ignoreprivileges=0)
 creates and processes a block allocation according to the passed in criteria
 XMLRPCprocessBlockTime ($blockTimesid, $ignoreprivileges=0)
 processes a block allocation for the blockTimes entry associated with blockTimesid

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 = '' 
)

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
XMLRPCaddRequestWithEnding ( imageid,
start,
end,
foruser = '' 
)

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

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 = '' 
)

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

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

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

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)