Archives/falk-werner_webfuse-provider
1
0
Fork 0
mirror of https://github.com/falk-werner/webfuse-provider synced 2026-03-02 04:09:18 +00:00
Code Issues Releases Wiki Activity

added API documentation

Browse Source
This commit is contained in:
Falk Werner
2020-02-17 21:53:42 +01:00
parent cd144a3143
commit 7b8616fcb3
26 changed files with 1215 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
include/webfuse/adapter/api.h
View File

@@ -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")))

18
include/webfuse/adapter/authenticate.h
View File

@@ -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);

48
include/webfuse/adapter/credentials.h
View File

@@ -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);

54
include/webfuse/adapter/mountpoint.h
View File

@@ -1,30 +1,76 @@
////////////////////////////////////////////////////////////////////////////////
/// \file adapter/mountpoint.h
/// \brief Mointpoint.
////////////////////////////////////////////////////////////////////////////////
#ifndef WF_ADAPTER_MOUNTPOINT_H
#define WF_ADAPTER_MOUNTPOINT_H
#include <webfuse/adapter/api.h>
#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,

15
include/webfuse/adapter/mountpoint_factory.h
View File

@@ -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,

32
include/webfuse/adapter/server.h
View File

@@ -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);

114
include/webfuse/adapter/server_config.h
View File

@@ -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
}

68
include/webfuse/adapter/server_protocol.h
View File

@@ -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,