1.. _module-pw_file: 2 3======= 4pw_file 5======= 6 7.. attention:: 8 9 ``pw_file`` is under construction, and may see significant breaking API 10 changes. 11 12The ``pw_file`` module defines a service for file system-like interactions 13between a client and server. FileSystem services may be backed by true file 14systems, or by virtual file systems that provide a file-system like interface 15with no true underlying file system. 16 17pw_file does not define a protocol for file transfers. 18:ref:`module-pw_transfer` provides a generalized mechanism for 19performing file transfers, and is recommended to be used in tandem with pw_file. 20 21----------- 22RPC service 23----------- 24The FileSystem RPC service is oriented to allow direct interaction, and has no 25sequenced protocol. Unlike FTP, all interactions are stateless. This service 26also does not yet define any authentication mechanism, meaning that all clients 27that can access a FileSystem service are granted equal permissions. 28 29.. literalinclude:: file.proto 30 :language: protobuf 31 :lines: 14- 32 33------------------------------ 34Flat FileSystem implementation 35------------------------------ 36This module provides the ``FlatFileSystemService``, an optional implementation 37of the FileSystem RPC service with a virtual interface that allows different 38data storage implementations to expose logical files. As the name implies, the 39file system is treated as a flat file system; it does not support any 40directory-like interactions. 41 42The ``FlatFileSystemService`` implementation requires a static, fixed list of 43``Entry`` pointers. Each ``Entry`` represents a potential 44file, and acts as an interface boundary that is backed by some kind of storage 45mechanism (e.g. ``BlobStore``, ``PersistentBuffer``). 46 47All ``Entry`` objects that should be enumerated by a 48``FlatFileSystemService`` MUST be named, and names must be globally unique to 49prevent ambiguity. Unnamed file entries will NOT be enumerated by a 50``FlatFileSystemService``, and are considered empty/deleted files. It is valid 51to have empty files that are enumerated with a name. 52 53``FlatFileSystemService`` requires two buffers at construction: one buffer for 54reading file names and another for encoding protobuf responses. The recommended 55encoding buffer size for a particular maximum file name length can be calculated 56with ``EncodingBufferSizeBytes``. For convenience, the 57``FlatFileSystemServiceWithBuffer<kMaxFileNameLength>`` class is provided. That 58class creates a ``FlatFileSystemService`` with a buffer automatically sized 59based on the maximum file name length. 60