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)