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 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)
Generated on Thu Feb 12 2015 16:49:38 for VCL XML RPC by   doxygen 1.8.5