From 7b8616fcb394c665435313c46f26233176a89a48 Mon Sep 17 00:00:00 2001 From: Falk Werner Date: Mon, 17 Feb 2020 21:53:42 +0100 Subject: [PATCH] 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