1<?php 2/* 3 * Copyright 2014 Google Inc. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); you may not 6 * use this file except in compliance with the License. You may obtain a copy of 7 * the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 13 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 14 * License for the specific language governing permissions and limitations under 15 * the License. 16 */ 17 18/** 19 * The "guardianInvitations" collection of methods. 20 * Typical usage is: 21 * <code> 22 * $classroomService = new Google_Service_Classroom(...); 23 * $guardianInvitations = $classroomService->guardianInvitations; 24 * </code> 25 */ 26class Google_Service_Classroom_Resource_UserProfilesGuardianInvitations extends Google_Service_Resource 27{ 28 /** 29 * Creates a guardian invitation, and sends an email to the guardian asking them 30 * to confirm that they are the student's guardian. Once the guardian accepts 31 * the invitation, their `state` will change to `COMPLETED` and they will start 32 * receiving guardian notifications. A `Guardian` resource will also be created 33 * to represent the active guardian. The request object must have the 34 * `student_id` and `invited_email_address` fields set. Failing to set these 35 * fields, or setting any other fields in the request, will result in an error. 36 * This method returns the following error codes: * `PERMISSION_DENIED` if the 37 * current user does not have permission to manage guardians, if the guardian in 38 * question has already rejected too many requests for that student, if 39 * guardians are not enabled for the domain in question, or for other access 40 * errors. * `RESOURCE_EXHAUSTED` if the student or guardian has exceeded the 41 * guardian link limit. * `INVALID_ARGUMENT` if the guardian email address is 42 * not valid (for example, if it is too long), or if the format of the student 43 * ID provided cannot be recognized (it is not an email address, nor a `user_id` 44 * from this API). This error will also be returned if read-only fields are set, 45 * or if the `state` field is set to to a value other than `PENDING`. * 46 * `NOT_FOUND` if the student ID provided is a valid student ID, but Classroom 47 * has no record of that student. * `ALREADY_EXISTS` if there is already a 48 * pending guardian invitation for the student and `invited_email_address` 49 * provided, or if the provided `invited_email_address` matches the Google 50 * account of an existing `Guardian` for this user. (guardianInvitations.create) 51 * 52 * @param string $studentId ID of the student (in standard format) 53 * @param Google_Service_Classroom_GuardianInvitation $postBody 54 * @param array $optParams Optional parameters. 55 * @return Google_Service_Classroom_GuardianInvitation 56 */ 57 public function create($studentId, Google_Service_Classroom_GuardianInvitation $postBody, $optParams = array()) 58 { 59 $params = array('studentId' => $studentId, 'postBody' => $postBody); 60 $params = array_merge($params, $optParams); 61 return $this->call('create', array($params), "Google_Service_Classroom_GuardianInvitation"); 62 } 63 /** 64 * Returns a specific guardian invitation. This method returns the following 65 * error codes: * `PERMISSION_DENIED` if the requesting user is not permitted to 66 * view guardian invitations for the student identified by the `student_id`, if 67 * guardians are not enabled for the domain in question, or for other access 68 * errors. * `INVALID_ARGUMENT` if a `student_id` is specified, but its format 69 * cannot be recognized (it is not an email address, nor a `student_id` from the 70 * API, nor the literal string `me`). * `NOT_FOUND` if Classroom cannot find any 71 * record of the given student or `invitation_id`. May also be returned if the 72 * student exists, but the requesting user does not have access to see that 73 * student. (guardianInvitations.get) 74 * 75 * @param string $studentId The ID of the student whose guardian invitation is 76 * being requested. 77 * @param string $invitationId The `id` field of the `GuardianInvitation` being 78 * requested. 79 * @param array $optParams Optional parameters. 80 * @return Google_Service_Classroom_GuardianInvitation 81 */ 82 public function get($studentId, $invitationId, $optParams = array()) 83 { 84 $params = array('studentId' => $studentId, 'invitationId' => $invitationId); 85 $params = array_merge($params, $optParams); 86 return $this->call('get', array($params), "Google_Service_Classroom_GuardianInvitation"); 87 } 88 /** 89 * Returns a list of guardian invitations that the requesting user is permitted 90 * to view, filtered by the parameters provided. This method returns the 91 * following error codes: * `PERMISSION_DENIED` if a `student_id` is specified, 92 * and the requesting user is not permitted to view guardian invitations for 93 * that student, if `"-"` is specified as the `student_id` and the user is not a 94 * domain administrator, if guardians are not enabled for the domain in 95 * question, or for other access errors. * `INVALID_ARGUMENT` if a `student_id` 96 * is specified, but its format cannot be recognized (it is not an email 97 * address, nor a `student_id` from the API, nor the literal string `me`). May 98 * also be returned if an invalid `page_token` or `state` is provided. * 99 * `NOT_FOUND` if a `student_id` is specified, and its format can be recognized, 100 * but Classroom has no record of that student. 101 * (guardianInvitations.listUserProfilesGuardianInvitations) 102 * 103 * @param string $studentId The ID of the student whose guardian invitations are 104 * to be returned. The identifier can be one of the following: * the numeric 105 * identifier for the user * the email address of the user * the string literal 106 * `"me"`, indicating the requesting user * the string literal `"-"`, indicating 107 * that results should be returned for all students that the requesting user is 108 * permitted to view guardian invitations. 109 * @param array $optParams Optional parameters. 110 * 111 * @opt_param string invitedEmailAddress If specified, only results with the 112 * specified `invited_email_address` are returned. 113 * @opt_param int pageSize Maximum number of items to return. Zero or 114 * unspecified indicates that the server may assign a maximum. The server may 115 * return fewer than the specified number of results. 116 * @opt_param string pageToken nextPageToken value returned from a previous list 117 * call, indicating that the subsequent page of results should be returned. The 118 * list request must be otherwise identical to the one that resulted in this 119 * token. 120 * @opt_param string states If specified, only results with the specified 121 * `state` values are returned. Otherwise, results with a `state` of `PENDING` 122 * are returned. 123 * @return Google_Service_Classroom_ListGuardianInvitationsResponse 124 */ 125 public function listUserProfilesGuardianInvitations($studentId, $optParams = array()) 126 { 127 $params = array('studentId' => $studentId); 128 $params = array_merge($params, $optParams); 129 return $this->call('list', array($params), "Google_Service_Classroom_ListGuardianInvitationsResponse"); 130 } 131 /** 132 * Modifies a guardian invitation. Currently, the only valid modification is to 133 * change the `state` from `PENDING` to `COMPLETE`. This has the effect of 134 * withdrawing the invitation. This method returns the following error codes: * 135 * `PERMISSION_DENIED` if the current user does not have permission to manage 136 * guardians, if guardians are not enabled for the domain in question or for 137 * other access errors. * `FAILED_PRECONDITION` if the guardian link is not in 138 * the `PENDING` state. * `INVALID_ARGUMENT` if the format of the student ID 139 * provided cannot be recognized (it is not an email address, nor a `user_id` 140 * from this API), or if the passed `GuardianInvitation` has a `state` other 141 * than `COMPLETE`, or if it modifies fields other than `state`. * `NOT_FOUND` 142 * if the student ID provided is a valid student ID, but Classroom has no record 143 * of that student, or if the `id` field does not refer to a guardian invitation 144 * known to Classroom. (guardianInvitations.patch) 145 * 146 * @param string $studentId The ID of the student whose guardian invitation is 147 * to be modified. 148 * @param string $invitationId The `id` field of the `GuardianInvitation` to be 149 * modified. 150 * @param Google_Service_Classroom_GuardianInvitation $postBody 151 * @param array $optParams Optional parameters. 152 * 153 * @opt_param string updateMask Mask that identifies which fields on the course 154 * to update. This field is required to do an update. The update fails if 155 * invalid fields are specified. The following fields are valid: * `state` When 156 * set in a query parameter, this field should be specified as 157 * `updateMask=,,...` 158 * @return Google_Service_Classroom_GuardianInvitation 159 */ 160 public function patch($studentId, $invitationId, Google_Service_Classroom_GuardianInvitation $postBody, $optParams = array()) 161 { 162 $params = array('studentId' => $studentId, 'invitationId' => $invitationId, 'postBody' => $postBody); 163 $params = array_merge($params, $optParams); 164 return $this->call('patch', array($params), "Google_Service_Classroom_GuardianInvitation"); 165 } 166} 167