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,

22
include/webfuse/core/status.h
View File

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

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

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

57
include/webfuse/provider/client.h
View File

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

149
include/webfuse/provider/client_config.h
View File

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

50
include/webfuse/provider/client_protocol.h
View File

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

28
include/webfuse/provider/dirbuffer.h
View File

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

15
include/webfuse/provider/operation/close.h
View File

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

14
include/webfuse/provider/operation/error.h
View File

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

24
include/webfuse/provider/operation/getattr.h
View File

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

25
include/webfuse/provider/operation/lookup.h
View File

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

25
include/webfuse/provider/operation/open.h
View File

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

34
include/webfuse/provider/operation/read.h
View File

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

27
include/webfuse/provider/operation/readdir.h
View File

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

38
include/webfuse/provider/static_filesystem.h
View File

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

5
include/webfuse_adapter.h
View File

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

5
include/webfuse_provider.h
View File

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