Skip to content

Share API

Jump to bottom
Bart Visscher edited this page May 24, 2013 · 13 revisions

Overview

The Share API is designed to manage the storage of shared items for the apps in ownCloud.

Definitions

  • Item - a resource e.g. test.txt (file), Birthdays (calendar), Coworkers (addressbook)
  • Item Type - the type of item e.g. file, calendar, addressbook
  • Share With - the person/people shared with e.g. user, group
  • Share Owner - a user who owns the item
  • Share - a connection between the share owner of an item and a share with the share owner wishes to share the item with
  • Share Type - the type of share with e.g. user, group, link, email address
  • Source - the identifier of the resource used by the app
  • Target - the name of the resource for the share with
  • Reshare - a share in which a recipient of a share shares that item to a different share with
  • Parent Share - the share that is the parent of another share, used for reshares and special case group shares
  • CRUDS - create, read, update, delete, share permissions defined in lib/public/constants.php
  • Collection - an item type that can have children items to share e.g. folder (files), calendar (events)

Classes

Share: Data holder for a share

Functions: getId(), getParentId(), getShareWith(), getShareType(), getShareOwner(), getPermissions(), setPermissions(), getItemSource(), getItemTarget(), getExpirationTime(), setExpirationTime()

ShareAPI: Abstract class extended by apps for their shared items. Implements marker interfaces to define the supported share types.

Abstract Functions:

  • isValidItem(Share $share)
  • getShareFactory()
  • isUniqueTargetRequired()
  • generateUniqueTarget(

Functions:

  • getShares($shareWith = null, $uidOwner = null, $isShareWithUser = true, $extraFilter = null)
  • getShareByTarget($itemTarget, $shareWith = null, $uidOwner = null, $isShareWithUser = true)
  • getShareBySource($itemSource, $shareWith = null, $uidOwner = null, $isShareWithUser = true)
  • getResharse(Share $share)
  • getDuplicates(Share $share)
  • getParent(Share $share, $find = false)
  • share(Share $share)
  • unshare(Share $share)
  • update(Share $share)
  • deleteItem($itemSource)
  • searchForShareWiths($pattern)
  • isExpired(Share $share)
  • areValidPermissions(Share $share)
  • updateResharesPermissions(Share $share, $oldPermissions)
  • isValidExpirationTime(Share $share)
  • updateREsharesExpirationTime(Share $share, $oldTime)

Utility: Helper class to get share type classes etc.

  • isEnabled()
  • Checks if the admin has the Share API enabled
  • isFileSharingEnabled()
  • Checks if the files_sharing app is enabled
  • getSupportedShareTypes($class)
  • Checks what marker interfaces the class implements
  • Returns share type objects
  • getSupportedShareType($class, $shareTypeId)
  • Return specified share type object

ShareType\ShareType: Abstract class that is responsible for inserting, updating, and deleting shares from the database. Extended by other share types to define their conditions for a valid share and additional custom handling. Uses the Item Factory provided by the app's ShareAPI to construct new Share objects.

Functions:

  • __construct($itemType, $itemFactory)
  • getShares($shareWith, $uidOwner, $isShareWithUser, $extraFilter)
  • isValidShare(Share $share)
  • share(Share $share)
  • unshare(Share $share)
  • Deletes share from database
  • Deletes all reshares from database
  • setPermissions(Share $share)
  • Checks if permissions are valid
  • If permissions are removed, updates permissions of all reshares
  • If share permission is removed, either delete all reshares or look for duplicates to switch parent ids
  • setExpirationTime(Share $share)
  • Checks if expiration time is valid
  • If time is decreased, either update time of all reshares or look for duplicates to switch parent ids
  • searchForShareWiths($pattern)
  • Returns a list of potential share with of this share type (for dropdown autocomplete)

ShareType\User extends ShareType\ShareType: Overridden functions:

  • isValidShare(Share $share)
  • Check if user exists
  • Check that share owner is not share with
  • Check admin sharing policy i.e. users in user's groups only
  • searchForShareWiths($pattern)
  • Return list of users matching $pattern

ShareType\Group extends ShareType\ShareType: Overridden functions:

  • isValidShare(Share $share)
  • Check if group exists
  • Check admin sharing policy i.e. user's groups only
  • share(Share $share)
  • Check if target conflicts for users in the group, create extra row in database with different target if conflict exists
  • searchForShareWiths($pattern)
  • Return list of groups matching $pattern

ShareType\Link extends ShareType\ShareType: Overridden functions:

  • isValidShare(Share $share)
  • Check if admin allows sharing via links
  • Check if item supports sharing via links
  • share(Share $share)
  • Generate token and save token, password in database with reference to share
  • unshare(Share $share)
  • Delete token in database
  • searchForShareWiths($pattern)
  • Return null
Clone this wiki locally