Writing a Files Storage Provider

In this short article we are going to learn how to write a simple Files Storage Provider for ScrewTurn Wiki 3.0 (STW from now on). A Files Storage Provider is a type of plugin that handles files-related data such as uploaded files/directories and page attachments

Introduction to Files Storage Providers¶

This brief section assumes you have already a general knowledge on STW providers.

The main task a Files Storage Provider performs is handling the following data on behalf of the wiki application:

• upload directories
• upload files
• page attachments.
  

Note: in case of read-only data (ReadOnly property returning true) the wiki application should never call methods that are intended for altering data. However, such methods that return collections should return empty collections instead of null. Methods that return single elements should return null instead.

All paths are specified in a UNIX-like format, for example /path/to/file.txt, but all paths are case-insensitive. All paths must start with a slash, and all directory paths must end with a slash too.

Directories Management¶

The following methods are called by the wiki application to manage directories:

• ListDirectories lists directories inside the specified directory
• CreateDirectory creates a directory inside the specified directory
• DeleteDirectory deletes a directory and all data inside it (files and sub-directories)
• RenameDirectory renames a directory.
  

Files Management¶

The following methods are called by the wiki application to manage files:

• ListFiles lists files inside the specified directory
• StoreFile stores a file inside the specified directory, reading from a source Stream and optionally counting the download
• RetrieveFile retrieves a file, writing into a destination Stream
• GetFileDetails returns an instance of FileDetails (or null if the file does not exist) containing information about the file (such as the size and number of downloads)
• SetFileRetrievalCount sets the number of times a file has been downloaded
• DeleteFile deletes a file and its download count
• RenameFile renames a file, preserving its download count.
  

Page Attachment Management¶

The following methods are called by the wiki application to manage page attachments:

• GetPagesWithAttachments lists the names of the pages that have at least one attachment
• ListPageAttachments lists the attachments a page has
• StorePageAttachment stores an attachment for the specified page, reading from a source Stream
• RetrievePageAttachment retrieves an attachment for the specified page, writing to a destination Stream and optionally counting the download
• GetPageAttachmentDetails returns an instance of FileDetails (or null if the attachment does not exist}} containing information about the attachment (such as the size and number of downloads)
• SetPageAttachmentRetrievalCount sets the number of time an attachment has been downloaded
• DeletePageAttachment deletes a page attachment and its download count
• RenamePageAttachment renames a page attachment, preserving its download count
• NotifyPageRenaming is called when a page is renamed (the provider should use this information to preserve the attachments data as well as their download count).