From a92428cbe1cf4897d9dc9f91f798c8e5f1554114 Mon Sep 17 00:00:00 2001 From: Falk Werner Date: Sun, 14 Jun 2020 14:17:36 +0200 Subject: [PATCH] added API docs --- include/webfuse/adapter/client.h | 96 ++++++++++++++++++++++ include/webfuse/adapter/client_callback.h | 37 ++++++--- include/webfuse/adapter/client_tlsconfig.h | 37 +++++++++ 3 files changed, 159 insertions(+), 11 deletions(-) diff --git a/include/webfuse/adapter/client.h b/include/webfuse/adapter/client.h index 1971106..29b4f17 100644 --- a/include/webfuse/adapter/client.h +++ b/include/webfuse/adapter/client.h @@ -14,42 +14,138 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wf_client +/// \brief Adapter client +/// +/// An adapter client is used to connect to a remote provider server, e.g. a +/// cloud service, an request a filesystem to inject. +//------------------------------------------------------------------------------ struct wf_client; +//------------------------------------------------------------------------------ +/// \brief Created a new instance of an adapter client. +/// +/// During creation, the client is initialized in the following order: +/// - WF_CLIENT_INIT is triggered to initialize custom data +/// - WF_CLIENT_GET_TLS_CONFIG is triggered to query TLS configuration +/// - internal initialization is performed +/// - WF_CLIENT_CREATED is triggered +/// +/// Therefore, the client should not be used, unless WF_CLIENT_CREATED is +/// triggered. +/// +/// When TLS configuration is queried, a pointer to an instance if +/// \see wf_client_tlsconfig is provided to be set by the user. +/// +/// \param callback Pointer to the callback function. +/// \param user_data Pointer to user data. +/// +/// \return Newly created instance of an adapter client. +//------------------------------------------------------------------------------ extern WF_API struct wf_client * wf_client_create( wf_client_callback_fn * callback, void * user_data); +//------------------------------------------------------------------------------ +/// \brief Disposes an adapter client. +/// +/// \param client Pointer to the client. +//------------------------------------------------------------------------------ extern WF_API void wf_client_dispose( struct wf_client * client); +//------------------------------------------------------------------------------ +/// \brief Get user data. +/// +/// \param client Pointer to the client. +//------------------------------------------------------------------------------ extern WF_API void * wf_client_get_userdata( struct wf_client * client); +//------------------------------------------------------------------------------ +/// \brief Triggers the client. +/// +/// \param client Pointer to the client. +//------------------------------------------------------------------------------ extern WF_API void wf_client_service( struct wf_client * client); +//------------------------------------------------------------------------------ +/// \brief Interrupts a service call. +/// +/// Wakes up the client. +/// +/// \note This is the only function that can be used safely from another +// thread. +/// +/// \param client Pointer to the client. +//------------------------------------------------------------------------------ extern WF_API void wf_client_interrupt( struct wf_client * client); +//------------------------------------------------------------------------------ +/// \brief Connects to a foreign server. +/// +/// Starts to connect. The callback is triggered, when connect is finised: +/// - WF_CLIENT_CONNECTED on success +/// - WF_CLIENT_DISCONNECTED on connect error +/// +/// \param client Pointer to the client. +/// \param url URL of the remote ppovider. +//------------------------------------------------------------------------------ extern WF_API void wf_client_connect( struct wf_client * client, char const * url); +//------------------------------------------------------------------------------ +/// \brief Disconnects from the foreign server. +/// +/// The event WF_CLIENT_DISCONNECTED is triggered, when disconnected. +/// +/// \param client Pointer to the client. +//------------------------------------------------------------------------------ extern WF_API void wf_client_disconnect( struct wf_client * client); +//------------------------------------------------------------------------------ +/// \brief Authenticated the client. +/// +/// During authentication, credentials are queries via +/// WF_CLIENT_AUTHENTICATE_GET_CREDENTIALS event. In that case a pointer to an +/// instance of wf_client_tlsconfig is provided to set credentials. +/// +/// When authentications finishes, an event is triggered: +/// - WF_CLIENT_AUTHENTICATED on success +/// - WF_CLIENT_AUTHENTICATION_FAILED on failure +/// +/// \param client Pointer to the client. +//------------------------------------------------------------------------------ extern WF_API void wf_client_authenticate( struct wf_client * client); +//------------------------------------------------------------------------------ +/// \brief Add a filesystem. +/// +/// After add filesystem finished, an event is triggered: +/// - WF_CLIENT_FILESYSTEM_ADDED on success +/// - WF_CLIENT_FILESYSTEM_ADD_FAILED on failure +/// +/// \note Currently, only one file system is supported by the client. +/// +/// \param client Pointer to the client. +/// \param local_path Local path where the filesystem should be places +/// (must be an exististing and empty directory). +/// \param name Name of the filesystem (identifier sent to the provider). +//------------------------------------------------------------------------------ extern WF_API void wf_client_add_filesystem( struct wf_client * client, diff --git a/include/webfuse/adapter/client_callback.h b/include/webfuse/adapter/client_callback.h index 90aabab..ad8bd86 100644 --- a/include/webfuse/adapter/client_callback.h +++ b/include/webfuse/adapter/client_callback.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/client_callbak.h +/// \brief Callback of adapter clients. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_CLIENT_CALLBACK_H #define WF_ADAPTER_CLIENT_CALLBACK_H @@ -7,24 +12,34 @@ extern "C" #endif -#define WF_CLIENT_INIT 0x0001 -#define WF_CLIENT_CLEANUP 0x0002 -#define WF_CLIENT_CREATED 0x0003 +#define WF_CLIENT_INIT 0x0001 ///< Out-most initialization of a client +#define WF_CLIENT_CLEANUP 0x0002 ///< Out-most cleanup of a client +#define WF_CLIENT_CREATED 0x0003 ///< Client is fully initialized an can be used -#define WF_CLIENT_CONNECTED 0x0011 -#define WF_CLIENT_DISCONNECTED 0x0012 +#define WF_CLIENT_CONNECTED 0x0011 ///< Connection to a foreign provider established +#define WF_CLIENT_DISCONNECTED 0x0012 ///< Connection closed or connect failed -#define WF_CLIENT_AUTHENTICATED 0x0021 -#define WF_CLIENT_AUTHENTICATION_FAILED 0x0022 -#define WF_CLIENT_AUTHENTICATE_GET_CREDENTIALS 0x0023 +#define WF_CLIENT_AUTHENTICATED 0x0021 ///< Authentication succeeded +#define WF_CLIENT_AUTHENTICATION_FAILED 0x0022 ///< Authentication failed +#define WF_CLIENT_AUTHENTICATE_GET_CREDENTIALS 0x0023 ///< Query credentials (\see wf_client_authenticate) -#define WF_CLIENT_FILESYSTEM_ADDED 0x0031 -#define WF_CLIENT_FILESYSTEM_ADD_FAILED 0x0032 +#define WF_CLIENT_FILESYSTEM_ADDED 0x0031 ///< File system added successfully +#define WF_CLIENT_FILESYSTEM_ADD_FAILED 0x0032 ///< Failed to add file system -#define WF_CLIENT_GET_TLS_CONFIG 0x0041 +#define WF_CLIENT_GET_TLS_CONFIG 0x0041 ///< Query TLS config (\see wf_client_create) struct wf_client; +//------------------------------------------------------------------------------ +/// \brief Client callback function +/// +/// This function is triggered whenever an event occurs the client should +/// be aware of. +/// +/// \param client Pointer to the client +/// \param reason Event, that triggered the callback +/// \param args Event-specific arguments +//------------------------------------------------------------------------------ typedef void wf_client_callback_fn( struct wf_client * client, int reason, diff --git a/include/webfuse/adapter/client_tlsconfig.h b/include/webfuse/adapter/client_tlsconfig.h index c2b5298..550b664 100644 --- a/include/webfuse/adapter/client_tlsconfig.h +++ b/include/webfuse/adapter/client_tlsconfig.h @@ -1,3 +1,8 @@ +//////////////////////////////////////////////////////////////////////////////// +/// \file adapter/client_tslconfig.h +/// \brief Configuration of TLS (Transport Layer Security) for adapter clients. +//////////////////////////////////////////////////////////////////////////////// + #ifndef WF_ADAPTER_CLIENT_TLSCONFIG_H #define WF_ADAPTER_CLIENT_TLSCONFIG_H @@ -8,18 +13,50 @@ extern "C" { #endif +//------------------------------------------------------------------------------ +/// \struct wf_client_tlsconfig +/// \brief TLS configuration of the client. +/// +/// TLS configuration is queried during initialization of a client via +/// WF_CLIENT_GET_TLS_CONFIG event. +/// +/// \see WF_CLIENT_GET_TLS_CONFIG +/// \see wf_client_create +//------------------------------------------------------------------------------ struct wf_client_tlsconfig; +//------------------------------------------------------------------------------ +/// \brief Sets the path to the private key. +/// +/// \note To enable TLS both, key_path and cert_path, must be specified. +/// +/// \param config Pointer to config. +/// \param key_path Path to private key file (in PEM format). +//------------------------------------------------------------------------------ extern WF_API void wf_client_tlsconfig_set_keypath( struct wf_client_tlsconfig * config, char const * key_path); +//------------------------------------------------------------------------------ +/// \brief Sets the path to the clients certificate. +/// +/// \note To enable TLS both, key_path and cert_path, must be specified. +/// +/// \param config Pointer to the config. +/// \param cert_path Path the the clients certificate (in PEM format). +//------------------------------------------------------------------------------ extern WF_API void wf_client_tlsconfig_set_certpath( struct wf_client_tlsconfig * config, char const * cert_path); +//------------------------------------------------------------------------------ +/// \brief Sets the path the CA file. +/// +/// \param config Pointer to the config. +/// \param cafile_path Path to CA file (in PEM format). +//------------------------------------------------------------------------------ extern WF_API void wf_client_tlsconfig_set_cafilepath( struct wf_client_tlsconfig * config,