From 7b8616fcb394c665435313c46f26233176a89a48 Mon Sep 17 00:00:00 2001 From: Falk Werner Date: Mon, 17 Feb 2020 21:53:42 +0100 Subject: [PATCH 1/2] added API documentation --- .gitignore | 1 + Doxyfile | 331 +++++++++++++++++++ include/webfuse/adapter/api.h | 16 + include/webfuse/adapter/authenticate.h | 18 + include/webfuse/adapter/credentials.h | 48 +++ include/webfuse/adapter/mountpoint.h | 54 ++- include/webfuse/adapter/mountpoint_factory.h | 15 + include/webfuse/adapter/server.h | 32 ++ include/webfuse/adapter/server_config.h | 114 ++++++- include/webfuse/adapter/server_protocol.h | 68 ++++ include/webfuse/core/status.h | 22 +- include/webfuse/provider/api.h | 16 + include/webfuse/provider/client.h | 57 ++++ include/webfuse/provider/client_config.h | 149 ++++++++- include/webfuse/provider/client_protocol.h | 50 +++ include/webfuse/provider/dirbuffer.h | 28 ++ include/webfuse/provider/operation/close.h | 15 + include/webfuse/provider/operation/error.h | 14 + include/webfuse/provider/operation/getattr.h | 24 ++ include/webfuse/provider/operation/lookup.h | 25 ++ include/webfuse/provider/operation/open.h | 25 ++ include/webfuse/provider/operation/read.h | 34 +- include/webfuse/provider/operation/readdir.h | 27 ++ include/webfuse/provider/static_filesystem.h | 38 +++ include/webfuse_adapter.h | 5 + include/webfuse_provider.h | 5 + 26 files changed, 1215 insertions(+), 16 deletions(-) create mode 100644 Doxyfile diff --git a/.gitignore b/.gitignore index 95be7aa..3aba301 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ /.build/ /.deps/ /.settings/language.settings.xml +/doc/api diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..7c48a25 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,331 @@ +# Doxyfile 1.8.13 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "webfuse" +PROJECT_NUMBER = 0.2.0 +PROJECT_BRIEF = "Websocket filesystem based on libfuse" +PROJECT_LOGO = +OUTPUT_DIRECTORY = "doc/api" +CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 4 +ALIASES = +TCL_SUBST = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +EXTENSION_MAPPING = +MARKDOWN_SUPPORT = YES +TOC_INCLUDE_HEADINGS = 0 +AUTOLINK_SUPPORT = YES +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +GROUP_NESTED_COMPOUNDS = NO +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = NO +LOOKUP_CACHE_SIZE = 0 +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +LAYOUT_FILE = +CITE_BIB_FILES = +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_AS_ERROR = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = README.md include +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.h +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = README.md +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = NO +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +CLANG_ASSISTED_PARSING = NO +CLANG_OPTIONS = +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = YES +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = wf_ wfp_ +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = +HTML_EXTRA_FILES = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_TIMESTAMP = NO +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = +QHG_LOCATION = +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = NO +GENERATE_TREEVIEW = NO +ENUM_VALUES_PER_LINE = 4 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +FORMULA_FONTSIZE = 10 +FORMULA_TRANSPARENT = YES +USE_MATHJAX = NO +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = +#--------------------------------------------------------------------------- +# Configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4 +EXTRA_PACKAGES = +LATEX_HEADER = +LATEX_FOOTER = +LATEX_EXTRA_STYLESHEET = +LATEX_EXTRA_FILES = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +LATEX_SOURCE_CODE = NO +LATEX_BIB_STYLE = plain +LATEX_TIMESTAMP = NO +#--------------------------------------------------------------------------- +# Configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +RTF_SOURCE_CODE = NO +#--------------------------------------------------------------------------- +# Configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_SUBDIR = +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# Configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- +GENERATE_DOCBOOK = NO +DOCBOOK_OUTPUT = docbook +DOCBOOK_PROGRAMLISTING = NO +#--------------------------------------------------------------------------- +# Configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# Configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration options related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +EXTERNAL_PAGES = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = YES +MSCGEN_PATH = +DIA_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +DOT_NUM_THREADS = 0 +DOT_FONTNAME = Helvetica +DOT_FONTSIZE = 10 +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO +DOT_PATH = +DOTFILE_DIRS = +MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = +PLANTUML_CFG_FILE = +PLANTUML_INCLUDE_PATH = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES diff --git a/include/webfuse/adapter/api.h b/include/webfuse/adapter/api.h index 5d00900..6ab7d30 100644 --- a/include/webfuse/adapter/api.h +++ b/include/webfuse/adapter/api.h @@ -1,10 +1,26 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/api.h +/// \brief API define for webfuse adapter. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_API_H #define WF_ADAPTER_API_H +//------------------------------------------------------------------------------ +/// \def WF_API +/// \brief Marks public symbols of libwebfuse_adapter. +//------------------------------------------------------------------------------ #ifndef WF_API #define WF_API #endif +//------------------------------------------------------------------------------ +/// \def WF_EXPORT +/// \brief Marks exported symbols as visible. +/// +/// Set WF_API to WF_EXPORT when building libwebfuse_adapter.so to export +/// public symbols. +//------------------------------------------------------------------------------ #ifndef WF_EXPORT #ifdef __GNUC__ #define WF_EXPORT __attribute__ ((visibility ("default"))) diff --git a/include/webfuse/adapter/authenticate.h b/include/webfuse/adapter/authenticate.h index e9113a6..e11e300 100644 --- a/include/webfuse/adapter/authenticate.h +++ b/include/webfuse/adapter/authenticate.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/authenticate.h +/// \brief Authenticate function. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_AUTHENTICATE_H #define WF_ADAPTER_AUTHENTICATE_H @@ -12,6 +17,19 @@ extern "C" struct wf_credentials; +//------------------------------------------------------------------------------ +/// \brief Authentication function type. +/// +/// Functions of this type are used to authenticate a user by some provided +/// credentials. +/// +/// \param credentials credentials to authenticate the user +/// \param user_data context of the authentication function +/// \return true, if authentication was successful, false otherwise +/// +/// \see wf_server_config_add_authenticator +/// \see wf_server_protocol_add_authenticator +//------------------------------------------------------------------------------ typedef bool wf_authenticate_fn( struct wf_credentials * credentials, void * user_data); diff --git a/include/webfuse/adapter/credentials.h b/include/webfuse/adapter/credentials.h index 82a8094..e3e65fc 100644 --- a/include/webfuse/adapter/credentials.h +++ b/include/webfuse/adapter/credentials.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/credentials.h +/// \brief Credentials used for user authentication. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_CREDENTIALS_H #define WF_ADAPTER_CREDENTIALS_H @@ -8,11 +13,54 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wf_credentials +/// \brief Credentials used for user authentication. +/// +/// Credentials are used during authentication to authenticate a user. +/// In order to support multiple types of credentials, e.g. username + password, +/// certifactes and / or authentication tokens, credentials are modelled as +/// opaque type with some access functions. +/// +/// \see wf_authenticate_fn +/// \see wf_credentials_type +/// \see wf_credentials_get +//------------------------------------------------------------------------------ struct wf_credentials; +//------------------------------------------------------------------------------ +/// \brief Returns the type of the credentials object. +/// +/// The type of the credentials objects defines, which keys are available +/// for a given instance. +/// +/// \note When an authenticate function is called, the credentials type +/// matches the type provided during _add_authenticator function call. +/// Therefore, it is not necessary to check credentials type within +/// the authenticate function. +/// +/// \note Within webfuse protocol documentation, only one type of credentials +/// is described byte now: username +/// +/// \param credentials Pointer to credentials object +/// \return type of the credentials object +/// +/// \see wf_server_config_add_authenticator +/// \see wf_server_protocol_add_authenticator +/// \see wf_authenticate_fn +//------------------------------------------------------------------------------ extern WF_API char const * wf_credentials_type( struct wf_credentials const * credentials); +//------------------------------------------------------------------------------ +/// \brief Return the value of a credentials item identified by the provided +/// key. +/// +/// \param credentials Pointer to credentials object. +/// \param key String to identify the item. +/// \return value of credentials item or null, if there is no item with that +/// key +//------------------------------------------------------------------------------ extern WF_API char const * wf_credentials_get( struct wf_credentials const * credentials, char const * key); diff --git a/include/webfuse/adapter/mountpoint.h b/include/webfuse/adapter/mountpoint.h index 62f59f3..9b77165 100644 --- a/include/webfuse/adapter/mountpoint.h +++ b/include/webfuse/adapter/mountpoint.h @@ -1,30 +1,76 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/mountpoint.h +/// \brief Mointpoint. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_MOUNTPOINT_H #define WF_ADAPTER_MOUNTPOINT_H +#include + #ifdef __cplusplus extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wf_mountpoint +/// \brief Mointpoint. +//------------------------------------------------------------------------------ struct wf_mountpoint; +//------------------------------------------------------------------------------ +/// \brief Disposes the user defined context of a mountpoint. +/// +/// \param user_data user defined context of the mointpoint. +/// +/// \see wf_mountpoint_set_userdata +//------------------------------------------------------------------------------ typedef void wf_mountpoint_userdata_dispose_fn( void * user_data); -extern struct wf_mountpoint * +//------------------------------------------------------------------------------ +/// \brief Creates a mountpoint. +/// +/// \param path local path of the mounpoint +/// \return Newly created mountpoint. +//------------------------------------------------------------------------------ +extern WF_API struct wf_mountpoint * wf_mountpoint_create( char const * path); -extern void +//------------------------------------------------------------------------------ +/// \brief Disposes a mountpoint. +/// +/// \param mountpoint pointer to the mountpoint +//------------------------------------------------------------------------------ +extern WF_API void wf_mountpoint_dispose( struct wf_mountpoint * mountpoint); -extern char const * +//------------------------------------------------------------------------------ +/// \brief Returns the local path of the mountpoint. +/// +/// \param mountpoint pointer to the mountpoint +/// \return local path of the mountpoint +//------------------------------------------------------------------------------ +extern WF_API char const * wf_mountpoint_get_path( struct wf_mountpoint const * mountpoint); -extern void +//------------------------------------------------------------------------------ +/// \brief Sets user data of the mointpoint. +/// +/// \note This function is intended for custom mountpoint factories to +/// annotate mountpoints with a user specified context. +/// +/// \param mounpoint pointer to the mountpoint +/// \param user_data user data +/// \param dispose pointer to dipose function of user data or NULL, +/// if there is no need to dispose user data +//------------------------------------------------------------------------------ +extern WF_API void wf_mountpoint_set_userdata( struct wf_mountpoint * mointpoint, void * user_data, diff --git a/include/webfuse/adapter/mountpoint_factory.h b/include/webfuse/adapter/mountpoint_factory.h index a265c6f..8a69821 100644 --- a/include/webfuse/adapter/mountpoint_factory.h +++ b/include/webfuse/adapter/mountpoint_factory.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/mountpoint_factory.h +/// \brief Defines a factory function to create mointpoints. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_MOUNTPOINT_FACTORY_H #define WF_ADAPTER_MOUNTPOINT_FACTORY_H @@ -10,6 +15,16 @@ extern "C" struct wf_mountpoint; +//------------------------------------------------------------------------------ +/// \brief Factory function to create mountpoints. +/// +/// \param filesystem name the filesystem +/// \param user_data context of the factory +/// \return newly created mountpoint or NULL, on error +/// +/// \see wf_server_config_set_mountpoint_factory +/// \see wf_server_protocol_create2 +//------------------------------------------------------------------------------ typedef struct wf_mountpoint * wf_create_mountpoint_fn( char const * filesystem, diff --git a/include/webfuse/adapter/server.h b/include/webfuse/adapter/server.h index 8a6a3a1..8e392ac 100644 --- a/include/webfuse/adapter/server.h +++ b/include/webfuse/adapter/server.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/server.h +/// \brief Adapter server. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_SERVER_H #define WF_ADAPTER_SERVER_H @@ -8,15 +13,42 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wf_server +/// \brief Webfuse adapter server object. +//------------------------------------------------------------------------------ struct wf_server; + struct wf_server_config; +//------------------------------------------------------------------------------ +/// \brief Creates a new server. +/// +/// \param config pointer to server configuration. +/// \return newly created server or NULL in case of an error +//------------------------------------------------------------------------------ extern WF_API struct wf_server * wf_server_create( struct wf_server_config * config); +//------------------------------------------------------------------------------ +/// \brief Disposes a server. +/// +/// \note server configuration is not managed by server. +/// +/// \param server pointer to server +//------------------------------------------------------------------------------ extern WF_API void wf_server_dispose( struct wf_server * server); +//------------------------------------------------------------------------------ +/// \brief Triggers the server. +/// +/// This function must be invoked in a loop while the server is running. It +/// makes the server wait for the next event and processes it. +/// +/// \param server pointer to server +/// \param timeout_ms timeout in milliseconds. +//------------------------------------------------------------------------------ extern WF_API void wf_server_service( struct wf_server * server, int timeout_ms); diff --git a/include/webfuse/adapter/server_config.h b/include/webfuse/adapter/server_config.h index 778cc8c..83a1c34 100644 --- a/include/webfuse/adapter/server_config.h +++ b/include/webfuse/adapter/server_config.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/server_config.h +/// \brief Server configuration. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_SERVER_CONFIG_H #define WF_ADAPTER_SERVER_CONFIG_H @@ -10,48 +15,153 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wf_server_config +/// \brief Holds configuration of webfuse adapter server. +//------------------------------------------------------------------------------ struct wf_server_config; +//------------------------------------------------------------------------------ +/// \brief Creates a new server configuration. +/// +/// \return newly created server configuration +//------------------------------------------------------------------------------ extern WF_API struct wf_server_config * wf_server_config_create(void); +//------------------------------------------------------------------------------ +/// \brief Disposes a server configuration. +/// +/// \note Contexts of mounpoint factory and added authenticators are not +/// disposed by default. +/// +/// \param config pointer of configuration object +/// +/// \see wf_server_config_set_mountpoint_factory +/// \see wf_server_config_add_authenticator +//------------------------------------------------------------------------------ extern WF_API void wf_server_config_dispose( struct wf_server_config * config); +//------------------------------------------------------------------------------ +/// \brief Sets a mountpoint path. +/// \deprecated This function will be removed soon. Use \ref +/// wf_server_config_set_mountpoint_factory instead. +/// +/// Sets the root path of UUID-based file system. +/// +/// \note A valid configuration needs either a mountpoint or a mounpoint +/// factory. +/// +/// \param config pointer of configuration object +/// \param mount_point root path of UUID-based file system. +//------------------------------------------------------------------------------ extern WF_API void wf_server_config_set_mountpoint( struct wf_server_config * config, char const * mount_point); +//------------------------------------------------------------------------------ +/// \brief Sets the mountpoint factory of the configuration. +/// +/// The mountpoint factory is called when a authenticated user adds a +/// filesystem. +/// +/// \note The user is responsible to manage the lifetime of the mountpoint +/// factory. +/// +/// \note A valid configuration needs either a mountpoint or a mounpoint +/// factory. +/// +/// \param config pointer of configuration object +/// \param create_mountpoint factory function to create a mountpoint +/// \param user_data context of mountpoint factory +//------------------------------------------------------------------------------ extern WF_API void wf_server_config_set_mountpoint_factory( struct wf_server_config * config, wf_create_mountpoint_fn * create_mountpoint, void * user_data); +//------------------------------------------------------------------------------ +/// \brief Sets the path of HTTP servers root context. +/// +/// Webfuse adapter server is capable of serving static HTTP context. This +/// function is used to specify the path of HTTP servers root context. +/// If not specified, no HTTP content is served. +/// +/// \param config pointer of configuration object +/// \param document_root path to static HTTP content +//------------------------------------------------------------------------------ extern WF_API void wf_server_config_set_documentroot( struct wf_server_config * config, char const * document_root); +//------------------------------------------------------------------------------ +/// \brief Sets the path to the servers private key. +/// +/// \note To enable TLS, private key and server certificate must be set. +/// Otherwise, only plain HTTP is supported. +/// +/// \param config pointer of configuration object +/// \param key_path path to servers private key (pem file) +//------------------------------------------------------------------------------ extern WF_API void wf_server_config_set_keypath( struct wf_server_config * config, char const * key_path); +//------------------------------------------------------------------------------ +/// \brief Sets path to servers certificate. +/// +/// \note To enable TLS, private key and server certificate must be set. +/// Otherwise, only plain HTTP is supported. +/// +/// \param config pointer of configuration object +/// \param cert_path path to servers certificate (pem file) +//------------------------------------------------------------------------------ extern WF_API void wf_server_config_set_certpath( struct wf_server_config * config, char const * cert_path); +//------------------------------------------------------------------------------ +/// \brief Sets the virtual hostname of the websockets server. +/// +/// \param config pointer of configuration object +/// \param vhost_name virtual hostname of the websockets server +//------------------------------------------------------------------------------ extern WF_API void wf_server_config_set_vhostname( struct wf_server_config * config, char const * vhost_name); +//------------------------------------------------------------------------------ +/// \brief Sets the port number of the websockets server. +/// +/// \param config pointer of configuration object +/// \param port port number of the websockets server +//------------------------------------------------------------------------------ extern WF_API void wf_server_config_set_port( struct wf_server_config * config, int port); +//------------------------------------------------------------------------------ +/// \brief Adds an authenticator. +/// +/// Authenticators are used to authenticate users by some provided credentials. +/// Multiple providers can be specified to support different types of +/// credentials. +/// +/// \note Adding multiple providers for the same credentials type results +/// in undefined behavior. +/// +/// \note The user is responsible to manage the lifetime of user data. +/// +/// \param config pointer to configuration object +/// \param type type of the credentials the authenticator supports +/// \param authenticate function called to authenticate a user +/// \param user_data context of authenticate function +//------------------------------------------------------------------------------ extern WF_API void wf_server_config_add_authenticator( struct wf_server_config * config, char const * type, wf_authenticate_fn * authenticate, - void * user_data -); + void * user_data); #ifdef __cplusplus } diff --git a/include/webfuse/adapter/server_protocol.h b/include/webfuse/adapter/server_protocol.h index 6491a05..8808669 100644 --- a/include/webfuse/adapter/server_protocol.h +++ b/include/webfuse/adapter/server_protocol.h @@ -1,3 +1,13 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/server_protocol.h +/// \brief Provides low level access to libwebsockets protocol. +/// +/// By default, libwebfuse encapsulates libwebsockets protocol by \ref +/// wf_server. But sometimes it might come in handy to have access to +/// libwebsockets protocol. This allows to integrate libwebfuse in existing +/// libwebsockets applications. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_SERVER_PROTOCOL_H #define WF_ADAPTER_SERVER_PROTOCOL_H @@ -10,23 +20,81 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wf_server_protocol +/// \brief Opaque webfuse server protocol. +//------------------------------------------------------------------------------ struct wf_server_protocol; + +//------------------------------------------------------------------------------ +/// \struct lws_protocols +/// \brief Forward declaration of libwebsockets protocols structure. +//------------------------------------------------------------------------------ struct lws_protocols; +//------------------------------------------------------------------------------ +/// \brief Creates a new protocol with a given mounpoint. +/// \deprecated This function will be removed soon. Use \ref +/// wf_server_protocol_create2 instead. +/// +/// \param mount_point root path of UUID-based file system. +/// \return newly created protocol +//------------------------------------------------------------------------------ extern WF_API struct wf_server_protocol * wf_server_protocol_create( char * mount_point); +//------------------------------------------------------------------------------ +/// \brief Creates a new protocol by a mountpoint factory. +/// +/// \note This function might be renamed in future releases. +/// +/// \note The user is responsible to manage the lifetime of mountpoint factory. +/// +/// \param create_mountpoint factory function to create mountpoints +/// \param create_mountpoint_context context of mountpoint factory +//------------------------------------------------------------------------------ extern WF_API struct wf_server_protocol * wf_server_protocol_create2( wf_create_mountpoint_fn * create_mountpoint, void * create_mountpoint_context); +//------------------------------------------------------------------------------ +/// \brief Disposes a protocol. +/// +/// \note Contexts of mountpoint factory and added authenticators are not +/// managed by dispose. +/// +/// \param protocol pointer to protocol +//------------------------------------------------------------------------------ extern WF_API void wf_server_protocol_dispose( struct wf_server_protocol * protocol); +//------------------------------------------------------------------------------ +/// \brief Intializes a libwebsockets protocol structure. +/// +/// \param protocol pointer to protocol +/// \param lws_protocols pointer to libwebsockets protocol structure +//------------------------------------------------------------------------------ extern WF_API void wf_server_protocol_init_lws( struct wf_server_protocol * protocol, struct lws_protocols * lws_protocol); +//------------------------------------------------------------------------------ +/// \brief Adds an authenticator. +/// +/// Authenticators are used to authenticate users by some provided credentials. +/// Multiple providers can be specified to support different types of +/// credentials. +/// +/// \note Adding multiple providers for the same credentials type results +/// in undefined behavior. +/// +/// \note The user is responsible to manage the lifetime of user data. +/// +/// \param protocol pointer to protocol +/// \param type type of the credentials the authenticator supports +/// \param authenticate function called to authenticate a user +/// \param user_data context of authenticate function +//------------------------------------------------------------------------------ extern WF_API void wf_server_protocol_add_authenticator( struct wf_server_protocol * protocol, char const * type, diff --git a/include/webfuse/core/status.h b/include/webfuse/core/status.h index 7b3c95f..49e53e5 100644 --- a/include/webfuse/core/status.h +++ b/include/webfuse/core/status.h @@ -1,17 +1,23 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file status.h +/// \brief Generic status code. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_STATUS_H #define WF_STATUS_H -#define WF_GOOD 0 -#define WF_BAD 1 +#define WF_GOOD 0 ///< Positive status code. +#define WF_BAD 1 ///< Generic negative status code. -#define WF_BAD_NOTIMPLEMENTED 2 -#define WF_BAD_TIMEOUT 3 -#define WF_BAD_BUSY 4 -#define WF_BAD_FORMAT 5 +#define WF_BAD_NOTIMPLEMENTED 2 ///< The called function is not implemented (yet). +#define WF_BAD_TIMEOUT 3 ///< A timeout occured. +#define WF_BAD_BUSY 4 ///< Resource is busy, try again later. +#define WF_BAD_FORMAT 5 ///< Invalid format. -#define WF_BAD_NOENTRY 101 -#define WF_BAD_ACCESS_DENIED 102 +#define WF_BAD_NOENTRY 101 ///< Entry not found. +#define WF_BAD_ACCESS_DENIED 102 ///< Access is denied. +/// Status code. typedef int wf_status; #endif diff --git a/include/webfuse/provider/api.h b/include/webfuse/provider/api.h index 5b3c572..963e038 100644 --- a/include/webfuse/provider/api.h +++ b/include/webfuse/provider/api.h @@ -1,10 +1,26 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/api.h +/// \brief API define for webfuse provider. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WFP_PROVIDER_API_H #define WFP_PROVIDER_API_H +//------------------------------------------------------------------------------ +/// \def WFP_API +/// \brief Marks public symbols of libwebfuse_provider. +//------------------------------------------------------------------------------ #ifndef WFP_API #define WFP_API #endif +//------------------------------------------------------------------------------ +/// \def WFP_EXPORT +/// \brief Marks exported symbols as visible. +/// +/// Set WFP_API to WFP_EXPORT when building libwebfuse_provider.so to export +/// public symbols. +//------------------------------------------------------------------------------ #ifndef WFP_EXPORT #ifdef __GNUC__ #define WFP_EXPORT __attribute__ ((visibility ("default"))) diff --git a/include/webfuse/provider/client.h b/include/webfuse/provider/client.h index 142bfae..b78fc4a 100644 --- a/include/webfuse/provider/client.h +++ b/include/webfuse/provider/client.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/client.h +/// \brief Webfuse provider client. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_PROVIDER_CLIENT_H #define WF_PROVIDER_CLIENT_H @@ -8,22 +13,74 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wfp_client +/// \brief Webfuse provider client. +//------------------------------------------------------------------------------ struct wfp_client; + struct wfp_client_config; +//------------------------------------------------------------------------------ +/// \brief Creates a webfuse provider client. +/// +/// \note Client configuration is not managed by the client. +/// +/// \param config pointer to client configuration. +/// \return newly created client or NULL in case of an error. +//------------------------------------------------------------------------------ extern WFP_API struct wfp_client * wfp_client_create( struct wfp_client_config * config); +//------------------------------------------------------------------------------ +/// \brief Connects the client to a remote webfuse adapter server. +/// +/// \note This call starts to establish a connection. A callback is invoked, +/// when the connection is estanlished. +/// +/// \param client pointer to client +/// \param url URL of remote webfuse adapter server +/// +/// \see wfp_connected_fn +/// \see wfp_client_config_set_onconnected +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_connect( struct wfp_client * client, char const * url); +//------------------------------------------------------------------------------ +/// \brief Disconnects a connected client. +/// +/// \note This call starts to disconnect the connection. A callback is invoked +/// when conntection is disconnected. +/// +/// \param client pointer to client +/// +/// \see wfp_disconnected_fn +/// \see wfp_client_config_set_ondisconnected +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_disconnect( struct wfp_client * client); +//------------------------------------------------------------------------------ +/// \brief Disposes a client. +/// +/// \note Client configuration is not managed by client. +/// +/// \param client pointer to client +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_dispose( struct wfp_client * client); +//------------------------------------------------------------------------------ +/// \brief Triggers the client. +/// +/// This function must be invoked in a loop while the client is running. It +/// makes the server wait for the next event and processes it. +/// +/// \param client pointer to client +/// \param timeout_ms timeout in milliseconds. +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_service( struct wfp_client * client, int timeout_ms); diff --git a/include/webfuse/provider/client_config.h b/include/webfuse/provider/client_config.h index 4a9cebc..73775f1 100644 --- a/include/webfuse/provider/client_config.h +++ b/include/webfuse/provider/client_config.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/client_config.h +/// \brief Client configuration of webfuse provider. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_PROVIDER_CLIENT_CONFIG_H #define WF_PROVIDER_CLIENT_CONFIG_H @@ -15,67 +20,209 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wfp_client_config +/// \brief Provider client configuration object. +/// +/// Holds configuration of webfuse provider client. +//------------------------------------------------------------------------------ struct wfp_client_config; +//------------------------------------------------------------------------------ +/// \brief Callback to signal when the client's connection is established. +/// +/// \param user_data user defined context +//------------------------------------------------------------------------------ typedef void wfp_connected_fn( void * user_data); +//------------------------------------------------------------------------------ +/// \brief Callback to signal when a client's connection is disconnected. +/// +/// \param user_data user defined context +//------------------------------------------------------------------------------ typedef void wfp_disconnected_fn( void * user_data); +//------------------------------------------------------------------------------ +/// \brief Callback to signal when a timer event occued. +/// +/// \param user_data user defined context +//------------------------------------------------------------------------------ typedef void wfp_ontimer_fn( void * user_data); +//------------------------------------------------------------------------------ +/// \brief Creates a new client configuration. +/// +/// \return newly created client configuration +//------------------------------------------------------------------------------ extern WFP_API struct wfp_client_config * wfp_client_config_create(void); +//------------------------------------------------------------------------------ +/// \brief Disposes a client configuration. +/// +/// \note The user defined context is not managed by the client configuration. +/// +/// \param config pointer to client configuration +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_dispose( struct wfp_client_config * config); +//------------------------------------------------------------------------------ +/// \brief Sets a user defined context. +/// +/// \note The user is responsible to manage the lifetime of user data. +/// +/// \param config pointer to client configuration +/// \param user_data user defined context +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_userdata( struct wfp_client_config * config, void * user_data); +//------------------------------------------------------------------------------ +/// \brief Sets the path to clients private key. +/// +/// \note To enable TLS both, private key and certificate, must be specified. +/// Otherwise, TLS is not used. +/// +/// \param config pointer to client configuration +/// \param key_path path of clients private key (pem file) +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_keypath( struct wfp_client_config * config, char const * key_path); +//------------------------------------------------------------------------------ +/// \brief Sets the path of clients certificate. +/// +/// \note To enable TLS both, private key and certificate, must be specified. +/// Otherwise, TLS is not used. +/// +/// \param config pointer to client configuration +/// \param cert_path path of the clients certificate (pem file) +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_certpath( struct wfp_client_config * config, char const * cert_path); +//------------------------------------------------------------------------------ +/// \brief Sets the onconnected handler. +/// +/// The handler is invoked, when the client's conntection is established. +/// +/// \param config pointer to client configuration +/// \param handler pointer to handler +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_onconnected( struct wfp_client_config * config, wfp_connected_fn * handler); +//------------------------------------------------------------------------------ +/// \brief Sets ondisconnected handler +/// +/// The handler is invoked, when the client's conntection is lost. +/// +/// \param config pointer to client configuration +/// \param handler pointer to handler +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_ondisconnected( struct wfp_client_config * config, wfp_disconnected_fn * handler); +//------------------------------------------------------------------------------ +/// \brief Sets ontimer handler. +/// +/// The handler is invoked, when a timer event occured. +/// +/// \param config pointer to client configuration +/// \param handler pointer to handler +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_ontimer( struct wfp_client_config * config, wfp_ontimer_fn * handler); - +//------------------------------------------------------------------------------ +/// \brief Sets onlookup handler. +/// +/// The handler is invoked, when the identifier of a file is requested. +/// +/// \param config pointer to client configuration +/// \param handler pointer to handler +/// +/// \see wfp_lookup_fn +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_onlookup( struct wfp_client_config * config, wfp_lookup_fn * handler); +//------------------------------------------------------------------------------ +/// \brief Sets ongetattr handler. +/// +/// The handler is invoked, when attributes of a file are requested. +/// +/// \param config pointer to client configuration +/// \param handler pointer to handler +/// +/// \see wfp_getattr_fn +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_ongetattr( struct wfp_client_config * config, wfp_getattr_fn * handler); +//------------------------------------------------------------------------------ +/// \brief Sets onreaddir handler. +/// +/// The handler is invoked, when the contents of directory are requested- +/// +/// \param config pointer to client configuration +/// \param handler pointer to handler +/// +/// \see wfp_readdir_fn +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_onreaddir( struct wfp_client_config * config, wfp_readdir_fn * handler); +//------------------------------------------------------------------------------ +/// \brief Sets onopen handler. +/// +/// The handler is invoked, whe a file should be opened. +/// +/// \param config pointer to client configuration +/// \param handler pointer to handler +/// +/// \see wfp_open_fn +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_onopen( struct wfp_client_config * config, wfp_open_fn * handler); +//------------------------------------------------------------------------------ +/// \brief Sets onclose handler. +/// +/// The handler is invoked, when a file is closed. +/// +/// \param config pointer to client configuration +/// \param handler pointer to handler +/// +/// \see wfp_close_fn +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_onclose( struct wfp_client_config * config, wfp_close_fn * handler); +//------------------------------------------------------------------------------ +/// \brief Sets onread handler. +/// +/// The handler is invoked, when a files content is requested. +/// +/// \param config pointer to client configuration +/// \param handler pointer to handler +/// +/// \see wfp_read_fn +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_config_set_onread( struct wfp_client_config * config, wfp_read_fn * handler); diff --git a/include/webfuse/provider/client_protocol.h b/include/webfuse/provider/client_protocol.h index 8bda896..bfb6d8a 100644 --- a/include/webfuse/provider/client_protocol.h +++ b/include/webfuse/provider/client_protocol.h @@ -1,3 +1,13 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/client_protocol.h +/// \brief Provides low level access to libwebsockets protocol. +/// +/// By default, libwebfuse encapsulates libwebsockets protocol by \ref +/// wfp_client. But sometimes it might come in handy to have access to +/// libwebsockets protocol. This allows to integrate libwebfuse in existing +/// libwebsockets applications. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_PROVIDER_CLIENT_PROTOCOL_H #define WF_PROVIDER_CLIENT_PROTOCOL_H @@ -8,17 +18,57 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wfp_client_protocol +/// \brief Opaque webfuse client protocol.. +//------------------------------------------------------------------------------ struct wfp_client_protocol; + +//------------------------------------------------------------------------------ +/// \struct wfp_provider +/// \brief Provider. +/// +/// \todo How is a user supposed to get a provider's instance? +//------------------------------------------------------------------------------ struct wfp_provider; + +//------------------------------------------------------------------------------ +/// \struct lws_protocols +/// \brief Forward declaration of libwebsockets protocols structure. +//------------------------------------------------------------------------------ struct lws_protocols; +//------------------------------------------------------------------------------ +/// \brief Creates a new webfuse provider client protocol. +/// +/// \note The user is responsible to manage lifetime of \arg user_data. +/// +/// \todo How is a user supposed to get a provider's instance? +/// +/// \param provider pointer to provider +/// \param user_data user defined context +/// \return newly created protocol +//------------------------------------------------------------------------------ extern WFP_API struct wfp_client_protocol * wfp_client_protocol_create( struct wfp_provider const * provider, void * user_data); +//------------------------------------------------------------------------------ +/// \brief Disposes a protocol. +/// +/// \note The user defined context is not managed by the protocol. +/// +/// \param protocol pointer to protocol. +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_protocol_dispose( struct wfp_client_protocol * protocol); +//------------------------------------------------------------------------------ +/// \brief Initialized libwebsockets protocol structure. +/// +/// \param protocol pointer to protocol +/// \param lws_protocol pointer to libwebsockets protocol structure. +//------------------------------------------------------------------------------ extern WFP_API void wfp_client_protocol_init_lws( struct wfp_client_protocol * protocol, struct lws_protocols * lws_protocol); diff --git a/include/webfuse/provider/dirbuffer.h b/include/webfuse/provider/dirbuffer.h index d0770e5..2737ab4 100644 --- a/include/webfuse/provider/dirbuffer.h +++ b/include/webfuse/provider/dirbuffer.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/dirbuffer.h +/// \brief Buffer used for directory listing. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_PROVIDER_DIRBUFFER_H #define WF_PROVIDER_DIRBUFFER_H @@ -12,13 +17,36 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wfp_dirbuffer +/// \brief Buffer used for directory listing. +/// +/// \see wfp_respond_readdir +//------------------------------------------------------------------------------ struct wfp_dirbuffer; +//------------------------------------------------------------------------------ +/// \brief Creates a new dir buffer. +/// +/// \return newly created dir buffer. +//------------------------------------------------------------------------------ extern WFP_API struct wfp_dirbuffer * wfp_dirbuffer_create(void); +//------------------------------------------------------------------------------ +/// \brief Disposes a dir buffer. +/// +/// \param buffer pointer to dir buffer +//------------------------------------------------------------------------------ extern WFP_API void wfp_dirbuffer_dispose( struct wfp_dirbuffer * buffer); +//------------------------------------------------------------------------------ +/// \brief Adds an entry to dir buffer. +/// +/// \param buffer pointer to dir buffer +/// \param name name of the entry (file or directory) +/// \param inode inode of the entry +//------------------------------------------------------------------------------ extern WFP_API void wfp_dirbuffer_add( struct wfp_dirbuffer * buffer, char const * name, diff --git a/include/webfuse/provider/operation/close.h b/include/webfuse/provider/operation/close.h index bb1eef1..ae17a28 100644 --- a/include/webfuse/provider/operation/close.h +++ b/include/webfuse/provider/operation/close.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/operation/close.h +/// \brief Provider's close callback. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WFP_OPERATION_CLOSE_H #define WFP_OPERATION_CLOSE_H @@ -18,6 +23,16 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \brief Callback invoked when a file is invoked. +/// +/// This function does not respond. +/// +/// \param inode inode of file to close +/// \param handle handle of file to close +/// \param flags file close flags +/// \param user_data user defined context +//------------------------------------------------------------------------------ typedef void wfp_close_fn( ino_t inode, uint32_t handle, diff --git a/include/webfuse/provider/operation/error.h b/include/webfuse/provider/operation/error.h index 4e8e1fe..556a630 100644 --- a/include/webfuse/provider/operation/error.h +++ b/include/webfuse/provider/operation/error.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/operation/error.h +/// \brief Respond with error code. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WFP_OPERATION_ERROR_H #define WFP_OPERATION_ERROR_H @@ -11,6 +16,15 @@ extern "C" struct wfp_request; +//------------------------------------------------------------------------------ +/// \brief Respond to a request with an error. +/// +/// A client's callback must respond with exactly one responde, either with a +/// valid reponse regarding to the concrete request or with an error response. +/// +/// \param request pointer to request +/// \param status error code +//------------------------------------------------------------------------------ extern WFP_API void wfp_respond_error( struct wfp_request * request, wf_status status); diff --git a/include/webfuse/provider/operation/getattr.h b/include/webfuse/provider/operation/getattr.h index 14af3dc..4c9564f 100644 --- a/include/webfuse/provider/operation/getattr.h +++ b/include/webfuse/provider/operation/getattr.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/operation/getattr.h +/// \brief Get file attributes. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WFP_OPERATION_GETATTR_H #define WFP_OPERATION_GETATTR_H @@ -14,11 +19,30 @@ extern "C" struct wfp_request; +//------------------------------------------------------------------------------ +/// \brief Get file attributes. +/// +/// \note After this function is called, exactly one response must be sent, +/// either via \ref wfp_respond_getattr or via \ref wfp_respond_error. +/// +/// \param request pointer to request +/// \param inode inode of file to get attributes +/// \param user_data user defined context +/// +/// \see wfp_respond_getattr +/// \see wfp_respond_error +//------------------------------------------------------------------------------ typedef void wfp_getattr_fn( struct wfp_request * request, ino_t inode, void * user_data); +//------------------------------------------------------------------------------ +/// \brief Respond to a get attributes request. +/// +/// \param request pointer to request +/// \param stat file attributes +//------------------------------------------------------------------------------ extern WFP_API void wfp_respond_getattr( struct wfp_request * request, struct stat const * stat); diff --git a/include/webfuse/provider/operation/lookup.h b/include/webfuse/provider/operation/lookup.h index 5e177d7..e8f9ca6 100644 --- a/include/webfuse/provider/operation/lookup.h +++ b/include/webfuse/provider/operation/lookup.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/operation/lookup.h +/// \brief Lookup file. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WFP_OPERATION_LOOKUP_H #define WFP_OPERATION_LOOKUP_H @@ -14,12 +19,32 @@ extern "C" struct wfp_request; +//------------------------------------------------------------------------------ +/// \brief Lookup a file or directory. +/// +/// \note After this function is called, exactly one response must be sent, +/// either via \ref wfp_respond_lookup or via \ref wfp_respond_error. +/// +/// \param request pointer to request +/// \param parent inode of parent +/// \param name name of the filesystem object to lookup +/// \param user_data pointer to user defined context +/// +/// \see wfp_respond_lookup +/// \see wfp_respond_error +//------------------------------------------------------------------------------ typedef void wfp_lookup_fn( struct wfp_request * request, ino_t parent, char const * name, void * user_data); +//------------------------------------------------------------------------------ +/// \brief Respond to lookup request. +/// +/// \param request pointer to request +/// \param stat attributes of filesystem object +//------------------------------------------------------------------------------ extern WFP_API void wfp_respond_lookup( struct wfp_request * request, struct stat const * stat); diff --git a/include/webfuse/provider/operation/open.h b/include/webfuse/provider/operation/open.h index 9114828..d5d9f9a 100644 --- a/include/webfuse/provider/operation/open.h +++ b/include/webfuse/provider/operation/open.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/operation/open.h +/// \brief Open a file. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WFP_OPERATION_OPEN_H #define WFP_OPERATION_OPEN_H @@ -20,12 +25,32 @@ extern "C" struct wfp_request; +//------------------------------------------------------------------------------ +/// \brief Open a file. +/// +/// \note After this function is called, exactly one response must be sent, +/// either via \ref wfp_respond_open or via \ref wfp_respond_error. +/// +/// \param request pointer to request +/// \param inode inode of the file to open +/// \param flags file open flags +/// \param user_data user defined context +/// +/// \see wfp_respond_open +/// \see wfp_respond_error +//------------------------------------------------------------------------------ typedef void wfp_open_fn( struct wfp_request * request, ino_t inode, int flags, void * user_data); +//------------------------------------------------------------------------------ +/// \brief Respond to open file. +/// +/// \param request pointer to request +/// \param handle handle of the opened file +//------------------------------------------------------------------------------ extern WFP_API void wfp_respond_open( struct wfp_request * request, uint32_t handle); diff --git a/include/webfuse/provider/operation/read.h b/include/webfuse/provider/operation/read.h index 570c310..64d0047 100644 --- a/include/webfuse/provider/operation/read.h +++ b/include/webfuse/provider/operation/read.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/operation/read.h +/// \brief Read contents of a file. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WFP_OPERATION_READ_H #define WFP_OPERATION_READ_H @@ -23,6 +28,25 @@ extern "C" struct wfp_request; +//------------------------------------------------------------------------------ +/// \brief Requests content of a file. +/// +/// On success, up to \arg length bytes should be returned via \ref +/// wfp_respond_read. +/// +/// \note After this function is called, exactly one response must be sent, +/// either via \ref wfp_respond_read or via \ref wfp_respond_error. +/// +/// \param request pointer to request +/// \param inode inode of the file to read +/// \param handle handle of the file to read (returned by open) +/// \param offset offset within the file where to start reading +/// \param length amount of bytes to read +/// \param user_data used defined context +/// +/// \see wfp_respond_read +/// \see wfp_respond_error +//------------------------------------------------------------------------------ typedef void wfp_read_fn( struct wfp_request * request, ino_t inode, @@ -31,12 +55,20 @@ typedef void wfp_read_fn( size_t length, void * user_data); +//------------------------------------------------------------------------------ +/// \brief Respond to read. +/// +/// \note The user is responsible to manage lifetime of \arg data. +/// +/// \param request pointer to request +/// \param data data read from file +/// \param length amount of bytes read +//------------------------------------------------------------------------------ extern WFP_API void wfp_respond_read( struct wfp_request * request, char const * data, size_t length); - #ifdef __cplusplus } #endif diff --git a/include/webfuse/provider/operation/readdir.h b/include/webfuse/provider/operation/readdir.h index 968b7f3..aef2f07 100644 --- a/include/webfuse/provider/operation/readdir.h +++ b/include/webfuse/provider/operation/readdir.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/operation/readdir.h +/// \brief List directory contents. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WFP_OPERATION_READDIR_H #define WFP_OPERATION_READDIR_H @@ -15,11 +20,33 @@ extern "C" struct wfp_dirbuffer; struct wfp_request; +//------------------------------------------------------------------------------ +/// \brief Requests the contents of a directory. +/// +/// \note After this function is called, exactly one response must be sent, +/// either via \ref wfp_respond_readdir or via \ref wfp_respond_error. +/// +/// \param request pointer to request +/// \param directory inode of directory to list +/// \param user_data user defined context +/// +/// \see wfp_respond_readdir +/// \see wfp_respond_error +//------------------------------------------------------------------------------ typedef void wfp_readdir_fn( struct wfp_request * request, ino_t directory, void * user_data); +//------------------------------------------------------------------------------ +/// \brief Respond to list directory contents. +/// +/// \note The user is responsible to manage dirbuffe, p.e. to dispose +/// it after this function is called. +/// +/// \param request pointer to request +/// \param dirbuffer contains contents of directory +//------------------------------------------------------------------------------ extern WFP_API void wfp_respond_readdir( struct wfp_request * request, struct wfp_dirbuffer * dirbuffer); diff --git a/include/webfuse/provider/static_filesystem.h b/include/webfuse/provider/static_filesystem.h index b2bdbfc..e736976 100644 --- a/include/webfuse/provider/static_filesystem.h +++ b/include/webfuse/provider/static_filesystem.h @@ -1,3 +1,13 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file provider/static_filesystem.h +/// \brief Reference implementation of static filesystem. +/// +/// This header is used by integration tests. It may be removed from the +/// library. +/// +/// \todo Remove this header from library +//////////////////////////////////////////////////////////////////////////////// + #ifndef WFP_STATIC_FILESYSTEM_H #define WFP_STATIC_FILESYSTEM_H @@ -16,8 +26,15 @@ extern "C" #endif struct wfp_client_config; + +//------------------------------------------------------------------------------ +/// \deprecated This will be removed. Dont use it. +//------------------------------------------------------------------------------ struct wfp_static_filesystem; +//------------------------------------------------------------------------------ +/// \deprecated This will be removed. Dont use it. +//------------------------------------------------------------------------------ typedef size_t wfp_static_filesystem_read_fn( size_t offset, @@ -25,6 +42,9 @@ wfp_static_filesystem_read_fn( size_t buffer_size, void * user_data); +//------------------------------------------------------------------------------ +/// \deprecated This will be removed. Dont use it. +//------------------------------------------------------------------------------ typedef void wfp_static_filesystem_get_info_fn( void * user_data, @@ -32,14 +52,23 @@ wfp_static_filesystem_get_info_fn( size_t * result_size); +//------------------------------------------------------------------------------ +/// \deprecated This will be removed. Dont use it. +//------------------------------------------------------------------------------ extern WFP_API struct wfp_static_filesystem * wfp_static_filesystem_create( struct wfp_client_config * config); +//------------------------------------------------------------------------------ +/// \deprecated This will be removed. Dont use it. +//------------------------------------------------------------------------------ extern WFP_API void wfp_static_filesystem_dispose( struct wfp_static_filesystem * filesystem); +//------------------------------------------------------------------------------ +/// \deprecated This will be removed. Dont use it. +//------------------------------------------------------------------------------ extern WFP_API void wfp_static_filesystem_add( struct wfp_static_filesystem * filesystem, @@ -48,6 +77,9 @@ wfp_static_filesystem_add( char const * content, size_t length); +//------------------------------------------------------------------------------ +/// \deprecated This will be removed. Dont use it. +//------------------------------------------------------------------------------ extern WFP_API void wfp_static_filesystem_add_text( struct wfp_static_filesystem * filesystem, @@ -55,12 +87,18 @@ wfp_static_filesystem_add_text( int mode, char const * content); +//------------------------------------------------------------------------------ +/// \deprecated This will be removed. Dont use it. +//------------------------------------------------------------------------------ extern WFP_API void wfp_static_filesystem_add_file( struct wfp_static_filesystem * filesystem, char const * path, char const * filename); +//------------------------------------------------------------------------------ +/// \deprecated This will be removed. Dont use it. +//------------------------------------------------------------------------------ extern WFP_API void wfp_static_filesystem_add_generic( struct wfp_static_filesystem * filesystem, diff --git a/include/webfuse_adapter.h b/include/webfuse_adapter.h index 37c39c2..af37c14 100644 --- a/include/webfuse_adapter.h +++ b/include/webfuse_adapter.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file webfuse_adapter.h +/// \brief Convenience header to include all functionality of libfuse_adapter. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_H #define WF_ADAPTER_H diff --git a/include/webfuse_provider.h b/include/webfuse_provider.h index e37fd68..5882c60 100644 --- a/include/webfuse_provider.h +++ b/include/webfuse_provider.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file webfuse_provider.h +/// \brief Convenience header to include all functionality of libfuse_provider. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_PROVIDER_H #define WF_PROVIDER_H From 4ae7160919cf463064f710a3f152ce62051391f6 Mon Sep 17 00:00:00 2001 From: Falk Werner Date: Tue, 18 Feb 2020 21:48:52 +0100 Subject: [PATCH 2/2] refactored README --- Doxyfile | 4 +- README.md | 416 ++------------------------------------------- doc/api.md | 55 ++++++ doc/build.md | 92 ++++++++++ doc/filesystem.png | Bin 5354 -> 0 bytes doc/filesystem.uml | 16 -- doc/protocol.md | 253 +++++++++++++++++++++++++++ 7 files changed, 414 insertions(+), 422 deletions(-) create mode 100644 doc/api.md create mode 100644 doc/build.md delete mode 100644 doc/filesystem.png delete mode 100644 doc/filesystem.uml create mode 100644 doc/protocol.md diff --git a/Doxyfile b/Doxyfile index 7c48a25..088248a 100644 --- a/Doxyfile +++ b/Doxyfile @@ -112,7 +112,9 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- # Configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = README.md include +INPUT = README.md \ + doc/build.md doc/protocol.md doc/api.md \ + include INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.h RECURSIVE = YES diff --git a/README.md b/README.md index d2cf16f..1c25a55 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,7 @@ webfuse combines libwebsockets and libfuse. It allows ot attach a remote filesys - [Fellow Repositories](#Fellow-Repositories) - [Concept](#Concept) - [Similar Projects](#Similar-Projects) -- [API](#API) -- [Build](#Build) -- [Dependencies](#Dependencies) +- [Further Documentation](#Further-Documentation) ## Motivation @@ -53,27 +51,14 @@ A reference implementation of such a daemon is provided within the examples. The - Whenever the user makes filesystem requests, such as *ls*, the request is redirected via webfuse daemon to the connected filesystem provider -Currently all requests are initiated by webfuse daemon and responded by filesystem provider. This may change in future, e.g. when authentication is supported. +### Adapters and Providers -### Filesystem represenation +In webfuse, an adapter is a component that adapts the libfuse API to a websocket interface. +Currently, libwebfuse implements only a server based adapter - a websocket server, that allows clients to connect a remote file system which +is represented via libfuse on the server side. -![filesystem](doc/filesystem.png) - -To handle multiple filesystems, that are registered by one or more providers, webfuse daemon maintains a directory structure as shown above. - -- **mount_point** is the entry point of the drectory structure - -- **fwupdate** is a name defined by the provider when filesystem was registered - *Note: the picture above shows two providers, where both registered a filesystem named "fwupdate"* - -- **<uuid>** is the filesystem id choosen by webfuse daemon to distinguish different filesystems - -- **default** is a symbolic link maintained by webfuse daemon to identify the default filesystem - -This directoy structure allows to handle multiple filesystems registered by multiple providers. -It can be used as a kind of service registry, where each filesystem represents a service. -The named subdirectores distinguish differend service types. The symbolic link *default* can be used to identify the -default service and the listing of a named subdirectory can be used to list available services of a particular type. +In webfuse, a provider is a component that provides a filesystem via websocket interface. +Currently, libwebfuse implements only a client based provider - a websocket client that provides a local filesystem to a remote server. ## Similar Projects @@ -83,387 +68,8 @@ default service and the listing of a named subdirectory can be used to list avai Unlike webfuse, davfs2 mounts a remote filesystem locally, that is provided by a WebDAV server. In contrast, webfuse starts a server awaiting client connections to attach the remote file system. -## API +## Further Documentation -### Requests, responses and notifications - -There are three types of messages, used for communication between webfuse daemon and filesystem provider. All message types are encoded in [JSON](https://www.json.org/) and strongly inspired by [JSON-RPC](https://www.jsonrpc.org/). - -#### Request - -A request is used by a sender to invoke a method on the receiver. The sender awaits a response from the receiver. Since requests and responses can be sendet or answered in any order, an id is provided in each request to identify it. - - { - "method": , - "params": , - "id" : - } - -| Item | Data type | Description | -| ----------- |:---------:| --------------------------------- | -| method_name | string | name of the method to invoke | -| params | array | method specific parameters | -| id | integer | id, which is repeated in response | - -#### Response - -A response is used to answer a prior request. There are two kinds of responses: - -##### Successful Results - - { - "result": , - "id": - } - -| Item | Data type | Description | -| ----------- |:---------:| ----------------------- | -| result | any | request specific result | -| id | integer | id, same as request | - -##### Error notifications - - { - "error": { - "code": - }, - "id": - } - -| Item | Data type | Description | -| ----------- |:---------:| ------------------- | -| code | integer | error code | -| id | integer | id, same as request | - -##### Error codes - -| Symbolic name | Code | Description | -| ------------------ | ---------:| ---------------------- | -| GOOD | 0 | no error | -| BAD | 1 | generic error | -| BAD_NOTIMPLEMENTED | 2 | method not implemented | -| BAD_TIMEOUT | 3 | timeout occured | -| BAD_BUSY | 4 | resource busy | -| BAD_FORMAT | 5 | invalid formt | -| BAD_NOENTRY | 101 | invalid entry | -| BAD_ACCESS_DENIED | 102 | access not allowed | - -#### Notification - -Notfications are used to inform a receiver about something. Unlike requests, notifications are not answered. Therefore, an id is not supplied. - - { - "method": , - "params": - } - -| Item | Data type | Description | -| ----------- |:---------:| --------------------------------- | -| method_name | string | name of the method to invoke | -| params | array | method specific parameters | - -### Requests (Adapter -> Provider) - -#### lookup - -Retrieve information about a filesystem entry by name. - - webfuse daemon: {"method": "lookup", "params": [, , ], "id": } - fs provider: {"result": { - "inode": , - "mode" : , - "type" : , - "size" : , - "atime": , - "mtime": , - "ctime": - }, "id": } - -| Item | Data type | Description | -| ----------- | --------------- | ------------------------------------------- | -| filesystem | string | name of the filesystem | -| parent | integer | inode of parent directory (1 = root) | -| name | string | name of the filesystem object to look up | -| inode | integer | inode of the filesystem object | -| mode | integer | unix file mode | -| type | "file" or "dir" | type of filesystem object | -| size | integer | required for files; file size in bytes | -| atime | integer | optional; unix time of last access | -| mtime | integer | optional; unix time of last modification | -| ctime | intefer | optional; unix time of last metadata change | - -#### getattr - -Get file attributes. - - webfuse daemon: {"method": "getattr", "params": [, ], "id": } - fs provider: {"result": { - "mode" : , - "type" : , - "size" : , - "atime": , - "mtime": , - "ctime": - }, "id": } - -| Item | Data type | Description | -| ----------- | --------------- | ------------------------------------------- | -| filesystem | string | name of the filesystem | -| inode | integer | inode of the filesystem object | -| mode | integer | unix file mode | -| type | "file" or "dir" | type of filesystem object | -| size | integer | required for files; file size in bytes | -| atime | integer | optional; unix time of last access | -| mtime | integer | optional; unix time of last modification | -| ctime | intefer | optional; unix time of last metadata change | - -#### readdir - -Read directory contents. -Result is an array of name-inode pairs for each entry. The generic entries -"." and ".." should also be provided. - - webfuse daemon: {"method": "readdir", "params": [, ], "id": } - fs provider: {"result": [ - {"name": , "inode": }, - ... - ], "id": } - -| Item | Data type | Description | -| ----------- | --------------- | ------------------------------ | -| filesystem | string | name of the filesystem | -| dir_inode | integer | inode of the directory to read | -| name | integer | name of the entry | -| inode | integer | inode of the entry | - -#### open - -Open a file. - - webfuse daemon: {"method": "readdir", "params": [, , ], "id": } - fs provider: {"result": {"handle": }, "id": } - -| Item | Data type | Description | -| ----------- | ----------| ----------------------------- | -| filesystem | string | name of the filesystem | -| inode | integer | inode of the file | -| flags | integer | access mode flags (see below) | -| handle | integer | handle of the file | - -##### Flags - -| Symbolic name | Code | Description | -| --------------| ---------:| --------------------------- | -| O_ACCMODE | 0x003 | access mode mask | -| O_RDONLY | 0x000 | open for reading only | -| O_WRONLY | 0x001 | open for writing only | -| O_RDWR | 0x002 | open for reading an writing | -| O_CREAT | 0x040 | create (a new) file | -| O_EXCL | 0x080 | open file exclusivly | -| O_TRUNC | 0x200 | open file to truncate | -| O_APPEND | 0x400 | open file to append | - -#### close - -Informs filesystem provider, that a file is closed. -Since `close` is a notification, it cannot fail. - - webfuse daemon: {"method": "close", "params": [, , , ], "id": } - -| Item | Data type | Description | -| ----------- | ----------| ---------------------------- | -| filesystem | string | name of the filesystem | -| inode | integer | inode of the file | -| handle | integer | handle of the file | -| flags | integer | access mode flags (see open) | - -#### read - -Read from an open file. - - webfuse daemon: {"method": "close", "params": [, , , , ], "id": } - fs provider: {"result": { - "data": , - "format": , - "count": - }, "id": } - -| Item | Data type | Description | -| ----------- | ----------| ----------------------------- | -| filesystem | string | name of the filesystem | -| inode | integer | inode of the file | -| handle | integer | handle of the file | -| offset | integer | Offet to start read operation | -| length | integer | Max. number of bytes to read | -| data | integer | handle of the file | -| format | string | Encoding of data (see below) | -| count | integer | Actual number of bytes read | - -##### Format - -| Format | Description | -| ---------- | -------------------------------------------------------- | -| "identiy" | Use data as is; note that JSON strings are UTF-8 encoded | -| "base64" | data is base64 encoded | - -### Requests (Provider -> Adapter) - -#### add_filesystem - -Adds a filesystem. - - fs provider: {"method": "add_filesytem", "params": [], "id": } - webfuse daemon: {"result": {"id": }, "id": } - -| Item | Data type | Description | -| ----------- | ----------| ------------------------------- | -| name | string | name and id of filesystem | - -#### authtenticate - -Authenticate the provider. -If authentication is enabled, a provider must be authenticated by the adapter before filesystems can be added. - - fs provider: {"method": "authenticate", "params": [, ], "id": } - webfuse daemon: {"result": {}, "id": } - -| Item | Data type | Description | -| ----------- | ----------| ------------------------------- | -| type | string | authentication type (see below) | -| credentials | object | credentials to authenticate | - -##### authentication types - -- **username**: authenticate via username and password - `{"username": , "password": }` - -## Authentication - -By default, webfuse daemon will redirect each filesystem call to the first connected provider without any authentication. -This might be good for testing purposes or when an external authentication mechanism is used. In some use cases, explicit authentication is needed. Therefore, authentication can be enabled within webfuse daemon. - -When authentication is enabled, filesystem calls are only redirected to a connected provider, after `authenticate` -has succeeded. - -![authenticate](doc/authenticate.png) - -### Enable authentication - -Authentication is enabled, if one or more authenticators are registered via `wf_server_config`. - - static bool authenticate(struct wf_credentials * creds, void * user_data) - { - char const * username = wf_credentials_get(creds, "username"); - char const * password = wf_credentials_get(creds, "password"); - - return ((NULL != username) && (0 == strcmp(username, "bob")) && - (NULL != password) && (0 == strcmp(password, "???"))); - } - - wf_server_config * config = wf_server_config_create(); - wf_server_config_add_authenticator(config, "username", &authenticate, NULL); - - wf_server * server = wf_server_create(config); - //... - -### Authenticator types and credentidals - -Each authenticator is identified by a user defined string, called `type`. The type is provided by the `authenticate` request, so you can define different authenticators for different authentication types, e.g. username, certificate, token. - -Actually, only one type is used: **username** -**It is strongly recommended to prefix custom authenticator types with an underscore (`_`) to avoid name clashes.** - -The `wf_credentials`struct represents a map to access credentials as key-value pairs, where both, key and value, are of type string. - -#### username - -The authenticator type **username** is used to authenticate via username and password. Valid credentials should contain two keys. - -- **username** refers to the name of the user -- **password** refers to the password of the user - -**Note** that no further encryption is done, so this authenticator type should not be used over unencrypted websocket connections. - -## Build - -To install dependencies, see below. - - cd webfuse - mkdir .build - cd .build - cmake .. - make - -### Build options - -By default, unit tests are enabled. You can disable them using the following cmake options: - -- **WITHOUT_TESTS**: disable tests - `cmake -DWITHOUT_TESTS=ON ..` - -Since webfuse consists of two libraries, it is possible to disable one of them -in order to reduce build dependencies. -*Note that unit tests are only available, when both libraries are built.* - -- **WITHOUT_ADAPTER**: omit adapter library - `cmake -DWITHOUT_ADAPTER=ON` - -- **WIHTOU_PROVIDER**: omit provider library - `cmake -DWITHOUT_PROVIDER=ON` - -## Dependencies - -- [libfuse3](https://github.com/libfuse/libfuse/) -- [libwebsockets](https://libwebsockets.org/) -- [Jansson](https://jansson.readthedocs.io) -- [GoogleTest](https://github.com/google/googletest) *(optional)* - -### Installation from source - -#### libfuse - -To install libfuse, meson is needed. Please refer to [meson quick guide](https://mesonbuild.com/Quick-guide.html) for setup instructions. - - wget -O fuse-3.8.0.tar.gz https://github.com/libfuse/libfuse/archive/fuse-3.8.0.tar.gz - tar -xf fuse-3.8.0.tar.gz - cd libfuse-fuse-3.8.0 - mkdir .build - cd .build - meson .. - ninja - sudo ninja install - -#### libwebsockets - - wget -O libwebsockets-3.2.0.tar.gz https://github.com/warmcat/libwebsockets/archive/v3.2.0.tar.gz - tar -xf libwebsockets-3.2.0.tar.gz - cd libwebsockets-3.2.0 - mkdir .build - cd .build - cmake .. - make - sudo make install - -#### Jansson - - wget -O libjansson-2.12.tar.gz https://github.com/akheron/jansson/archive/v2.12.tar.gz - tar -xf libjansson-2.12.tar.gz - cd jansson-2.12 - mkdir .build - cd .build - cmake .. - make - sudo make install - -#### GoogleTest - -Installation of GoogleTest is optional webfuse library, but required to compile tests. - - wget -O gtest-1.10.0.tar.gz https://github.com/google/googletest/archive/release-1.10.0.tar.gz - tar -xf gtest-1.10.0.tar.gz - cd googletest-release-1.10.0 - mkdir .build - cd .build - cmake .. - make - sudo make install +- [Build instructions](doc/build.md) +- [Webfuse Protocol](doc/protocol.md) +- [API](doc/api.md) diff --git a/doc/api.md b/doc/api.md new file mode 100644 index 0000000..6cd8340 --- /dev/null +++ b/doc/api.md @@ -0,0 +1,55 @@ +# Webfuse API introduction + +This introduction provides a general overview to webfuse API. +Please refer to the [build instructions](build.md) to generate API reference documentation. + +## Contents + +- [Authentication](#Authentication) + +## Authentication + +By default, webfuse daemon will redirect each filesystem call to the first connected provider without any authentication. +This might be good for testing purposes or when an external authentication mechanism is used. In some use cases, explicit authentication is needed. Therefore, authentication can be enabled within webfuse daemon. + +When authentication is enabled, filesystem calls are only redirected to a connected provider, after `authenticate` +has succeeded. + +![authenticate](authenticate.png) + +### Enable authentication + +Authentication is enabled, if one or more authenticators are registered via `wf_server_config`. + + static bool authenticate(struct wf_credentials * creds, void * user_data) + { + char const * username = wf_credentials_get(creds, "username"); + char const * password = wf_credentials_get(creds, "password"); + + return ((NULL != username) && (0 == strcmp(username, "bob")) && + (NULL != password) && (0 == strcmp(password, "???"))); + } + + wf_server_config * config = wf_server_config_create(); + wf_server_config_add_authenticator(config, "username", &authenticate, NULL); + + wf_server * server = wf_server_create(config); + //... + +### Authenticator types and credentidals + +Each authenticator is identified by a user defined string, called `type`. The type is provided by the `authenticate` request, so you can define different authenticators for different authentication types, e.g. username, certificate, token. + +Actually, only one type is used: **username** +**It is strongly recommended to prefix custom authenticator types with an underscore (`_`) to avoid name clashes.** + +The `wf_credentials`struct represents a map to access credentials as key-value pairs, where both, key and value, are of type string. + +#### username + +The authenticator type **username** is used to authenticate via username and password. Valid credentials should contain two keys. + +- **username** refers to the name of the user +- **password** refers to the password of the user + +**Note** that no further encryption is done, so this authenticator type should not be used over unencrypted websocket connections. diff --git a/doc/build.md b/doc/build.md new file mode 100644 index 0000000..9a90ea3 --- /dev/null +++ b/doc/build.md @@ -0,0 +1,92 @@ +# Build Instructions + +To install dependencies, see below. + + cd webfuse + mkdir .build + cd .build + cmake .. + make + +## Build options + +By default, unit tests are enabled. You can disable them using the following cmake options: + +- **WITHOUT_TESTS**: disable tests + `cmake -DWITHOUT_TESTS=ON ..` + +Since webfuse consists of two libraries, it is possible to disable one of them +in order to reduce build dependencies. +*Note that unit tests are only available, when both libraries are built.* + +- **WITHOUT_ADAPTER**: omit adapter library + `cmake -DWITHOUT_ADAPTER=ON` + +- **WIHTOU_PROVIDER**: omit provider library + `cmake -DWITHOUT_PROVIDER=ON` + +## Create API documentation + +To create API documentation, you must install doxygen and dot first. +After that, run doxygen in the project root directory. + + doxygen + +After that, you will find the API documentation in the doc/api subdirectory. + +## Dependencies + +- [libfuse3](https://github.com/libfuse/libfuse/) +- [libwebsockets](https://libwebsockets.org/) +- [Jansson](https://jansson.readthedocs.io) +- [GoogleTest](https://github.com/google/googletest) *(optional)* + +### Installation from source + +#### libfuse + +To install libfuse, meson is needed. Please refer to [meson quick guide](https://mesonbuild.com/Quick-guide.html) for setup instructions. + + wget -O fuse-3.8.0.tar.gz https://github.com/libfuse/libfuse/archive/fuse-3.8.0.tar.gz + tar -xf fuse-3.8.0.tar.gz + cd libfuse-fuse-3.8.0 + mkdir .build + cd .build + meson .. + ninja + sudo ninja install + +#### libwebsockets + + wget -O libwebsockets-3.2.0.tar.gz https://github.com/warmcat/libwebsockets/archive/v3.2.0.tar.gz + tar -xf libwebsockets-3.2.0.tar.gz + cd libwebsockets-3.2.0 + mkdir .build + cd .build + cmake .. + make + sudo make install + +#### Jansson + + wget -O libjansson-2.12.tar.gz https://github.com/akheron/jansson/archive/v2.12.tar.gz + tar -xf libjansson-2.12.tar.gz + cd jansson-2.12 + mkdir .build + cd .build + cmake .. + make + sudo make install + +#### GoogleTest + +Installation of GoogleTest is optional webfuse library, but required to compile tests. + + wget -O gtest-1.10.0.tar.gz https://github.com/google/googletest/archive/release-1.10.0.tar.gz + tar -xf gtest-1.10.0.tar.gz + cd googletest-release-1.10.0 + mkdir .build + cd .build + cmake .. + make + sudo make install diff --git a/doc/filesystem.png b/doc/filesystem.png deleted file mode 100644 index 4b4106a5baa940e2e070fac600acdbbf8f44384c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 5354 zcmZWtc|6o_*S4=?8A~RblCh3tkTAArG?ub&m2I*{2s3usqcA0F3WMxxveVcK*%|v1 zij1AIgwp%f?|Gm1`Ml3Rv)jVCQKmd8ecq>vnF#iL*yaUXZY}z zWB<#>#@fbN%l>6H&zI=|{WCIN%|338`T4JGAdh#@a_>Sh5Mh)#8u-Gz#?X#g98SA8%ie8Ysv_xn-CeWr0eO9SNVO6zV&L70 zV7xAme36hK3rFHiT?Raa8pt;onoF)^{P9dRzMu1P^PuG6N5hA-mdr2>C$ z*UmkwLnqm>{GRSAUfmN#xTxNRsMufMCz zr+i)aa6$cHd{Ppw6YBHp$AD@jbgyh5hH12g(0$B>{c-JdiaM^StE;Q8ug}W5sHn)d zIU2_&w>e$AHLN39T38s$>gwuBkRBZ!m5`8d87tA!(J3x3=h20pm2v1TZ$4>o8NXcj z-mJv@;+&Z z5wF}DwB&K9vl0D($Im-6Mh;SqRI|@Gm;*okBl5 zuk5oq(|mHo%xh$5sD!f{DKNm{aGlRCr2MH4i!0+nn>TizeXcLpsa5fdE8fg%T8%x9+o0|4#C^wdt_WdFl?Tmm= z49~Ws;`+zqpKyv0e}0K^aB*x0z}{XLS<}3Kzwk(b97fCB@$7=+w3nBcd))$^UtqUb z{)3r11Nmm*XAV0jyCgk;;P3tSc;(z?62*)X@v*$JOfy0vBJKI##T~uBZ)PY5*iZx= z?Vi2jG$=Em1kOy}f|%vT}0mvx*PruT4%g`nWrB z=|a`s`9`rqkw6m0#>RX;`_cEy?!$mz?o`@oSy^QS<_;ggfNV&@;SFnLjr$wZ2S7=% zot0h$q8=Quhjg%gMt-^GjnFkf3Q*l;o8WIc{Pv2Qo12!F_95H&=%^)b)a1KS6n^5i z%v|7)TXV#q(Px(3-Q9x+X(T<>ptZ5m>>PaHpWg@kR;x41nZYMxciml8!vS6JB}Y?R z-oj#`Vv>^9RZc@Cx8GR>|K3|&UA6B?Ze{re>`ady6nW2aCydbY8FiKFo#TKhl4_cL z;@JtC^9o*0nlXoCTf1ZGBc26Jx~3#KcTXNCA4YjXNdpkO4Yb(wepLSv(BA zIaAMRCFDjt{MH&yUpze>e-g8a2CB?)3vF{isZO1F^7~+J+q&YA4q?;M`%Or z5YybeJl1pa4?n#SD*FBY;IsIpOE-0N6aiT^E4M10s&$*aV_^Z>aD46Y7)~vU>{v*# zegr7DmY&|$T(c^Tz5^t>rTo+4^O4L~8h(4DW&jJ*;^Per3_Qq#7bhV__`2oX!a~N& zSyfddzxYGk9NQnW0Gy6=`P9>Mml){RiN9RHuOB+PV}V1mhC2zG*eRtvg$k`^pOcBf ztKFN=~$%QRLwu^I~z6qIXPy3uBZB&i|!AQy1?BbbfvN})MG&B_U*}3Dci6iFa(aG zqx&)Gn5hnk*RtCVFRLB%t=tK7SCYq>z3HFGU3EwQ7cA8gP01syJ>V8#h2jV|M5eC|ze-RFn^ zMG>uoo~jM8$mX7&~W4+zu8YNb?}a=6q`!G0Z@bF2&OOWg1K|m2Q(?)7XYqnL-bZ zY*4%M!q_f0S0GxnUa~vmHWtJ&OZm8P2tD<^XlnfN!~McAig6r-I7n8Iz=11#&56lM6rk@aHyWP%KqipQX;r zp)XBHh7m<(9NTZwoWDrtRqM5^8$_$PUcg$xxiVg!8B5K3liG(J)!AZ5&Cn6AE=P_Q z&PVx5{0$zu&ABmt!Bx) zH6S;eRL#z3-SdyA$KeVEMB@4L!m9zbMPLWrl_8h%_sN-=>J z5A_HobR{c6i0nr>F70&0_4G=K#-%~K+oF#|4<5(Y%LTc zt)Wt{UIXMZRw+{vcQSOJKvrT`4DZv|ko*wX^qQf9QF_CK`qCJPPW~S2eBPFukY8?>Js9IBVWgGqA zK}Hu@atfm!x4e0^bJ8!Tk59R`i$tGYzg1!Sb!ek~!+-3yV=L|nUVH+BrpgcT@x9t| zV$I$<0<90Xp-<)w$%jqe|`Hx0way?=4{bDkmOwpO0m2(p@XhBPXz^vjs5i#&HQy z@KQQ2`9j)|R#i^%N~Rvqiz$=S9z=~k-1*2;Y((>xmuuVHRGbZThKsAq)>$=7H@Ri= zOxA4Z)5S%*g{mB*+qcDjR1Dgz%7=x}{dH9h!i5#w=z{1(K7H{uTX4TO+m^7dXqxk( zM$b}F+ZgvIuIs;C4Wpa&TTW-U-|M+b4>U_1Jv~+5ZGto9@#-x;fJ3+V^14qL73xx@ z?U}0hnhU7sJ$BoHDfe(W6PTtKLnx^enYrmxhe}FHL^6D-RGgii;c$4^%DBWtv08pZ z1FvcR3}d^Ij`EJWcEy>A*?Ts>0%@wLQxv?u-K-0qpWI$bu?`EzdHfKtJQa888Jn6iSK49ti(imx}NVNJpN&&QV9&TdTR!kCX7IY&%Jio;^bR z(eXwtFbVCikkEf};*Jlt=r!m=!!gBk6LNQC-=C4Rx}+NB!^Eyawl*}ZwC_1H3A72y z51Vbwk`a!~N_e;WrR3z~Gn1_2Wz(q4!wPe8I9ys4J@n%HaEQB z-&%b_61|d&bYedjnoBqDy@=4%7>))t7<1i79E{=E?KQO3hwKlHiZc95OA(+1-@oG@ z&wq4BT?XhRc;Qm7{tu&Hu_8ZrpEH0@TOo)Pi84VeCGfKpfHdHo@jvXtBbcbT&C{P_ zKVaD778zej@@)Ytu!Dk{)K{*@ccT^qZ}+EEOKM{VF3Hk8alK#}$J9>zI>q_oG6@W0 z9PV%0?bT0wNGyr?VL!`bKX3^NESmF@o!ZAK{jmRuR z1%>vf$S-p{2#EEZVgvSl=y=9+Y$$MSOtAT{jB%jRVFSlx zc$ii@Ce?S5W*A&Vr!is!#c*(s#gki+ZG!N(xiDkP;^!RB8iW~CZHpY(M9QXdtlZLI zg5veq$Ov$TaCCHJ?#(06#|pO@nzbT!bZ5w#nvB&PIgkqCg)BJJT8I&uG&1r=j?Ty? zRXakXJPgAT(zVJEIav+et>MB_F{ed26P{A8A=OQ|#whcFQ=k;D&?Z&8@fSvaZcqXR zN*~=u@m@lM%vkLtWn+mhc-n@XH~y_5t2Ti;waWAb4iTn|mVjoh?q%zF!r7AGbS2|Q zxqxZ1>Y3aJ+0@^DGk9f#?;_Pl*ZLTRvXcM)uYALp>#~HzXgVC41+2;Azzh}Jq|)%$ zU?YmgUvb`3m$(C(DAZz9u_Bg!6!%`rqTZkP0>e zlWHzJg{;g;V5;+XAVn~_`+Z4EO(UlA-o!@N;K{kJg`Q2ViKTlZ;Gzb&z0%M6TJh%O zq@+)h`IIkTzAQ@ruCZ79Hb?=13`p+6UDIGI&06aOa|?{bGyI}7TWR~5(?{M_pt~`N z&U$UQLAF6f>wb-KT8oCyuZngm!lEmy-Jl-EX1TFOUhcMLk0Q_9R_qA*7v@9k4V^_p z`RwJgEOB+LAep@$IvMgeIT4q1@((xs4~y`zFq`=|NJLi9Q{-|E|A+3z;bxzYAbz z)s_VS&<6X^@TzpfjS(Bse8y{Uu!7I=2a-1$;g{w`JH_v>nb#zDZ|?QZXcQOoc4*ja zDkpdhb(aeen793bW2k4p!g9f|Hq&%UV{^oJA*o^fYpk$`iXx>fTu`IL(Y?QvLK96wbunVsL<+*5q)M0*g8M zb?D%NwnjPycmI`UAJcTnZ-px*aZ}ZGDQ>|1OgNCbXO4>iiKA z#Ccz!0EP+qoGkE=eu^>Cn684q@@hR%vK@brJZ7 Za@|c+MQhBn1h~Vb(9+OFm8si={SRI2Miu}7 diff --git a/doc/filesystem.uml b/doc/filesystem.uml deleted file mode 100644 index 1b78837..0000000 --- a/doc/filesystem.uml +++ /dev/null @@ -1,16 +0,0 @@ -@startuml - -salt -{ -{T -+ mount_point -++ fwupdate -+++ default -> 7c029f81-6bdf-4d3c-82dc-26f748164012 -+++ 7c029f81-6bdf-4d3c-82dc-26f748164012 -++++ update.raucb -+++ f93de23b-4535-4a47-a287-a381b78a11b8 -++++ update.raucb -} -} - -@enduml \ No newline at end of file diff --git a/doc/protocol.md b/doc/protocol.md new file mode 100644 index 0000000..5245b3d --- /dev/null +++ b/doc/protocol.md @@ -0,0 +1,253 @@ +# Webfuse Protocol + +## Requests, responses and notifications + +There are three types of messages, used for communication between webfuse daemon and filesystem provider. All message types are encoded in [JSON](https://www.json.org/) and strongly inspired by [JSON-RPC](https://www.jsonrpc.org/). + +### Request + +A request is used by a sender to invoke a method on the receiver. The sender awaits a response from the receiver. Since requests and responses can be sendet or answered in any order, an id is provided in each request to identify it. + + { + "method": , + "params": , + "id" : + } + +| Item | Data type | Description | +| ----------- |:---------:| --------------------------------- | +| method_name | string | name of the method to invoke | +| params | array | method specific parameters | +| id | integer | id, which is repeated in response | + +### Response + +A response is used to answer a prior request. There are two kinds of responses: + +#### Successful Results + + { + "result": , + "id": + } + +| Item | Data type | Description | +| ----------- |:---------:| ----------------------- | +| result | any | request specific result | +| id | integer | id, same as request | + +#### Error notifications + + { + "error": { + "code": + }, + "id": + } + +| Item | Data type | Description | +| ----------- |:---------:| ------------------- | +| code | integer | error code | +| id | integer | id, same as request | + +#### Error codes + +| Symbolic name | Code | Description | +| ------------------ | ---------:| ---------------------- | +| GOOD | 0 | no error | +| BAD | 1 | generic error | +| BAD_NOTIMPLEMENTED | 2 | method not implemented | +| BAD_TIMEOUT | 3 | timeout occured | +| BAD_BUSY | 4 | resource busy | +| BAD_FORMAT | 5 | invalid formt | +| BAD_NOENTRY | 101 | invalid entry | +| BAD_ACCESS_DENIED | 102 | access not allowed | + +### Notification + +Notfications are used to inform a receiver about something. Unlike requests, notifications are not answered. Therefore, an id is not supplied. + + { + "method": , + "params": + } + +| Item | Data type | Description | +| ----------- |:---------:| --------------------------------- | +| method_name | string | name of the method to invoke | +| params | array | method specific parameters | + +## Requests (Adapter -> Provider) + +### lookup + +Retrieve information about a filesystem entry by name. + + webfuse daemon: {"method": "lookup", "params": [, , ], "id": } + fs provider: {"result": { + "inode": , + "mode" : , + "type" : , + "size" : , + "atime": , + "mtime": , + "ctime": + }, "id": } + +| Item | Data type | Description | +| ----------- | --------------- | ------------------------------------------- | +| filesystem | string | name of the filesystem | +| parent | integer | inode of parent directory (1 = root) | +| name | string | name of the filesystem object to look up | +| inode | integer | inode of the filesystem object | +| mode | integer | unix file mode | +| type | "file" or "dir" | type of filesystem object | +| size | integer | required for files; file size in bytes | +| atime | integer | optional; unix time of last access | +| mtime | integer | optional; unix time of last modification | +| ctime | intefer | optional; unix time of last metadata change | + +### getattr + +Get file attributes. + + webfuse daemon: {"method": "getattr", "params": [, ], "id": } + fs provider: {"result": { + "mode" : , + "type" : , + "size" : , + "atime": , + "mtime": , + "ctime": + }, "id": } + +| Item | Data type | Description | +| ----------- | --------------- | ------------------------------------------- | +| filesystem | string | name of the filesystem | +| inode | integer | inode of the filesystem object | +| mode | integer | unix file mode | +| type | "file" or "dir" | type of filesystem object | +| size | integer | required for files; file size in bytes | +| atime | integer | optional; unix time of last access | +| mtime | integer | optional; unix time of last modification | +| ctime | intefer | optional; unix time of last metadata change | + +### readdir + +Read directory contents. +Result is an array of name-inode pairs for each entry. The generic entries +"." and ".." should also be provided. + + webfuse daemon: {"method": "readdir", "params": [, ], "id": } + fs provider: {"result": [ + {"name": , "inode": }, + ... + ], "id": } + +| Item | Data type | Description | +| ----------- | --------------- | ------------------------------ | +| filesystem | string | name of the filesystem | +| dir_inode | integer | inode of the directory to read | +| name | integer | name of the entry | +| inode | integer | inode of the entry | + +### open + +Open a file. + + webfuse daemon: {"method": "readdir", "params": [, , ], "id": } + fs provider: {"result": {"handle": }, "id": } + +| Item | Data type | Description | +| ----------- | ----------| ----------------------------- | +| filesystem | string | name of the filesystem | +| inode | integer | inode of the file | +| flags | integer | access mode flags (see below) | +| handle | integer | handle of the file | + +#### Flags + +| Symbolic name | Code | Description | +| --------------| ---------:| --------------------------- | +| O_ACCMODE | 0x003 | access mode mask | +| O_RDONLY | 0x000 | open for reading only | +| O_WRONLY | 0x001 | open for writing only | +| O_RDWR | 0x002 | open for reading an writing | +| O_CREAT | 0x040 | create (a new) file | +| O_EXCL | 0x080 | open file exclusivly | +| O_TRUNC | 0x200 | open file to truncate | +| O_APPEND | 0x400 | open file to append | + +### close + +Informs filesystem provider, that a file is closed. +Since `close` is a notification, it cannot fail. + + webfuse daemon: {"method": "close", "params": [, , , ], "id": } + +| Item | Data type | Description | +| ----------- | ----------| ---------------------------- | +| filesystem | string | name of the filesystem | +| inode | integer | inode of the file | +| handle | integer | handle of the file | +| flags | integer | access mode flags (see open) | + +### read + +Read from an open file. + + webfuse daemon: {"method": "close", "params": [, , , , ], "id": } + fs provider: {"result": { + "data": , + "format": , + "count": + }, "id": } + +| Item | Data type | Description | +| ----------- | ----------| ----------------------------- | +| filesystem | string | name of the filesystem | +| inode | integer | inode of the file | +| handle | integer | handle of the file | +| offset | integer | Offet to start read operation | +| length | integer | Max. number of bytes to read | +| data | integer | handle of the file | +| format | string | Encoding of data (see below) | +| count | integer | Actual number of bytes read | + +#### Format + +| Format | Description | +| ---------- | -------------------------------------------------------- | +| "identiy" | Use data as is; note that JSON strings are UTF-8 encoded | +| "base64" | data is base64 encoded | + +## Requests (Provider -> Adapter) + +### add_filesystem + +Adds a filesystem. + + fs provider: {"method": "add_filesytem", "params": [], "id": } + webfuse daemon: {"result": {"id": }, "id": } + +| Item | Data type | Description | +| ----------- | ----------| ------------------------------- | +| name | string | name and id of filesystem | + +### authtenticate + +Authenticate the provider. +If authentication is enabled, a provider must be authenticated by the adapter before filesystems can be added. + + fs provider: {"method": "authenticate", "params": [, ], "id": } + webfuse daemon: {"result": {}, "id": } + +| Item | Data type | Description | +| ----------- | ----------| ------------------------------- | +| type | string | authentication type (see below) | +| credentials | object | credentials to authenticate | + +#### authentication types + +- **username**: authenticate via username and password + `{"username": , "password": }`