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