IPWorks Cloud 2020 PHP Edition

Questions / Feedback?

UpdatePermissions Method

Create, update, and delete permissions on a file, folder, or shared drive.

Object Oriented Interface

public function doUpdatePermissions($resourceid);

Procedural Interface

ipworkscloud_googledrive_do_updatepermissions($res, $resourceid);

Remarks

This method is used to create, update, and delete permissions for the file, folder, or shared drive specified by ResourceId.

Each item represented by the Permission* properties has a PermissionModOp property which can be set to one of the following values:

moNone (0) (default) No-Op (the class skips the permission).
moCreate (1) The permission will be created.
moUpdate (2) The permission will be updated.
moDelete (3) The permission will be deleted.

When this method is called, the class will iterate through the Permission* properties and execute the requested operation for each permission.

For each permission operation which completes successfully, the class will change its PermissionModOp property back to moNone (0).

Important: The class executes permission operations one-by-one due to how the Google Drive API works. If the class encounters an issue during one of the operations, it will fail with an error, and won't attempt to execute any remaining permission items' operations. The error message will indicate the index of the permission item which caused the error.

Usage

ListPermissions must be called before using this method in order to populate the Permission* properties with a resource's existing permissions. (When creating new permissions, calling ListPermissions first is optional, but still recommended to ensure that the class reflects the latest information.)

To create new permissions, add new items to the Permission* properties by incrementing the PermissionCount property as necessary.

For each permission being created or updated, set its properties to the desired values. The PermissionModOp property should be set to a value other than moNone (0) for any permission that should be created, updated, or deleted.

Once the permission items have been set up as desired, call this method.

// For simplicity's sake, assume that this file currently has no permissions on it.
string fileId = "awd0s79uocijl23wf";

// Add permissions for a couple of users to the file.
googledrive.Permissions.Add(new GDrivePermission() {
  Email = "fakeuser1@example.com",
  Role = GDrivePermissionRoles.prReader,
  ModOp = GDrivePermissionModOps.moCreate
});
googledrive.Permissions.Add(new GDrivePermission() {
  Email = "fakeuser2@example.com",
  Role = GDrivePermissionRoles.prWriter,
  ModOp = GDrivePermissionModOps.moCreate
});
googledrive.UpdatePermissions(fileId);

// Now we'll update the permissions on the file, removing one of the users and
// changing the other's role to "Commenter". Always list the permissions first
// to ensure that the latest data is loaded into the class.
googledrive.ListPermissions(fileId);
googledrive.Permissions[0].ModOp = GDrivePermissionModOps.moDelete;
googledrive.Permissions[1].Role = GDrivePermissionRoles.prCommenter;
googledrive.Permissions[1].ModOp = GDrivePermissionModOps.moUpdate;

// Now commit the changes.
googledrive.UpdatePermissions(fileId);

Transferring Ownership

When creating or updating a permission with the prOwner (3) role on a file or folder, the old owner will have their role downgraded to prWriter (2). The TransferOwnership configuration setting must be set to "True" before calling UpdatePermissions to acknowledge this side effect.

Note that this does not apply to shared drives themselves, or resources in shared drives. It also does not apply when moving resources into or out of shared drives.

Shared Drive Permissions

The permissions on a shared drive itself determine what users are members of the shared drive, and what capabilities they have within the shared drive. Said another way, creating, updating, and deleting the permissions on a shared drive will create, update the capabilities of, and delete shared drive memberships.

Since members are determined by the permissions on a shared drive, this method can of course be used to manipulate one or more shared drive members at once. For simpler use cases which only need to modify one member at a time, the AddSharedDriveMember, UpdateSharedDriveMember, and RemoveSharedDriveMember convenience methods can be used.

Note: Only the ptUser (0) and ptGroup (1) permission types are valid for permissions on a shared drive itself.

Just like in a regular user's drive, permissions can also be applied to files within a shared drive to explicitly share them with specific users (whether they're members of the shared drive or not).

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks Cloud 2020 PHP Edition - Version 20.0 [Build 8265]