Lib:Architecture/Base Layer/Filesystem Module
From GNUpdf
| Library Module | |
|---|---|
| Filesystem Module | |
| Layer | Base |
| API Documentation | Reference Manual |
| Source Files | src/base/pdf-fsys.h |
Contents |
Overview
This module provides facilities to access filesystem objects (files, folders, file permissions, etc) in a system-independent way.
Concepts and Definitions
This section cover the most important concepts involved in the Filesystem module. Filesystem objects provides access to file system services in an abstract way, letting the library client to define filesystems for other classes of devices. Open files are readable or writeable file items in a filesystem. Path names are named locations identifying files or folders.
Filesystem
In the GNU PDF Library a filesystem object (of type pdf_fsys_t) is an implementation of the file system services for a specific class of devices. The filesystem object provides the functionality to open files, read and write data from/to open files, create and delete folders, rename files, manage file and folder permissions, etc.
By implementing the functions defined in the Filesystem Implementation Interface the client can define and use its own filesystems. In this way a high level of abstraction is achieved in the library code that uses the filesystem services: the library is able to read the contents of a PDF file from a file stored in the local filesystem, from a network webdav based filesystem, an http server or a compressed image.
The GNU PDF Library provides the default disk filesystem implementation for each supported plattform.
Filesystem Item
Conceptually speaking a filesystem contain a tree (or several trees in some filesystem implementations supporting several volumes) of filesystem items.
Each time has a type and several properties. The client can ask the filesystem for the properties of a given item identified by a path name. Those properties are summarized in the pdf_fsys_item_props_s structure and are the following:
- type: The type of the item. Supported types are:
- File
- Folder
- Unknown
- hidden_p: Tells if the item has set the hidden bit.
- is_read_only_p: Tells if the item has set the read-only bit.
- creation_date_known: Tells if the creation date (see below) is useful.
- creation_date: The creation date of the item.
- mod_date_known: Tells if the last modification date (see below) is useful.
- mod_date: The last modification date of the item.
- file_size: If the item is a file then this field contain the lower 32-bits of the size (in octects) of the item.
- file_size_high: If the item is a file then this field contain the upper 32-bits of the size (in octects) of the item.
- folder_size: If the item is a folder then this field contain the number of items contained in the folder.
File
An open file object (of type pdf_fsys_file_t) represent a readable and/or writable file in a filesystem. Open files are associated with a given filesystem and any filesystem can maintain an arbitrary number of open files (this may depend on the specific filesystem implementation).
The client can read and write data from/to an open file using the pdf_fsys_file_* functions. The implementation of the open files then call to the appropriate functionality of the filesystem managing the file.
The client should close any opened file calling the appropriate function on the underlying filesystem.
Folder
There is not an explicit data type for an open folder in the GNU PDF Library. Instead, folders are referred using path names.
The Filesystem Interface provides functions to create, delete and rename folders.
Path name
Both files and folders in a filesystem can be referred using a string locator: a path name. Path names are implemented using PDF strings. Several path names can refer to the same file or folder.
Both the encoding and the format of the contents of a path name depends on the specific filesystem implementation. The default disk filesystem provided by the GNU PDF Library uses the textual device idependent file specifications described in the PDF Reference (section 3.10). The interpretation of those path names depend in the specific plattform where the library is running. See XXX for more information about the disk filesystem path names.
Relation between Path Names, Open Files and Filesystems
The following datamodel depicts the relation between path names, open files and filesystems:
Interfaces
This section describes several interfaces that can be found in the Filesystem module. There is an internal interface filesystem implementors can implement to define a new filesystem. It is called the Filesystem Implementation Interface. A Filesystem Definition Interface allow users to register the implementation functions into a filesystem variable. There are also two interfaces implemented by the Filesystem module allowing clients to access the module functionality: the Filesystem Interface, used to manage several filesystem aspects, and the File Interface, that provides functionalities related to open files, such as reading and writing information.
The following interface diagram show the relation between the filesystem interface, the filesystem definition interface, the filesystem implementation interface and the file interface:
The Filesystem Implementation Interface
The filesystem implementation interface is a set of functions that are installed in a pdf_fsys_t variable in order to provide its functionality. By implementing those functions the client can provide a filesystem for some (physical or logical) storage device: a webdav directory, a read-only http filesystem, etc.
Note that the functions conforming the Implementation Interface are not intended to be directly invoked by clients. Clients can access to the functionality of the filesystem using indirect ways:
- Making calls to the Filesystem Interface.
- Making calls to the File Interface.
The implementation of both interfaces then makes use of the Filesystem Implementation Interface in order to honour the petition.
Details about the Filesystem Implementation Interface can be found in the GNU PDF Library Reference Manual, section XXX.
The Filesystem Definition Interface
The Filesystem Definition Interface is implemented by the Filesystem module and provides functionality to provide an implementation to a filesystem. A pdf_fsys_t should be properly defined before to use it.
The Filesystem Definition Interface defines the following elements:
- The function types conforming the Filesystem Implementation Interface.
- Installation functions to register implementation functions into a filesystem variable.
The Filesystem Interface
The Filesystem Interface is implemented by the Filesystem module and provides access to some filesystem functionalities in a filesystem implementation independent way.
The functionality covered by the Filesystem Interface includes:
- Folder management.
- Folder contents management.
- Volume-level flush operations.
- Read In Advance (RIA) capabilities.
- Storage properties management (free space, etc).
- Management of filesystem items (rename, remove, flags, etc).
- Utility functions (get a path name for a temporal file, etc).
Note that not all the filesystem implementations support these operations. Read In Advance capabilities, for example, are usually implemented in slow file system devices such as network filesystems. When a specific filesystem implementation do not support a functionality in the Filesystem Interface then the specific call becomes a no-op.
Details about the Filesystem Interface can be found in the GNU PDF Library Reference Manual, section XXX.
The File Interface
The File Interface is implemented by the filesystem module and provides access to filesystem functionality related with open files, such as writing and reading data to/from a specific file.
Note that open file variables (pdf_fsys_file_t) contain a reference to its underlying filesystem implementation, so the client should only provide a correctly initialized (opened) file variable to the pdf_fsys_file_* functions.
The functionality covered by the File Interface includes:
- Synchronous Input/Output.
- Asynchronoous Input/Output (not to be confused with RIA. See above).
- File-level flush operations.
- File positioning management.
- File size management.
- File flags (status) management.
Details about the File Interface can be found in the GNU PDF Library Reference Manual, section XXX.
The Disk Filesystem
TBD
