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