Webserver Plugin
One of the cores of the innovaphone App Platform is the webserver (see "The core of the innovaphone App Platform" for details). An App can plugin itself to the webserver
to receive HTTP or websocket requests. If an App whants to offer an JavaScript UI too, it actually must plugin itself into the webserver. However, this can be done by using the IWebserverPlugin interface.
The app needs to give a path to the IWebserverPlugin on creation and call IWebserverPlugin::HttpListen(), IWebserverPlugin::WebsocketListen() or IWebserverPlugin::PassthroughListen() to receive the different requests.
The path given to the interface on creation will be the applications web root. So if e. G. the system is accassibly under http://<IP_ADDRESS> and the application passes "/myapp" as path, it will be accessibly under
http://<IP_ADDRESS>/myapp, wich will be the apps root. The root of the system is reserved for the Manager of the innovaphone App Platform. The application will receive every request to that path and below.
The webserver plugin is a collection of a bunch of interfaces, used for web communication. Each web request type (like GET, PUT, POST, ...) has it's own interface to handle the request. They also have ther own user class
an application must subclass and pass to the IWebserverPlugin isntance to accept a request. This user class is responsible for sending and receiveing data, settings additional informations (like chunk encoded transfer, the number
of bytes the response have, the data type of the response).
The IWebserverPlugin also supports static files. Those files will be converted to a C++ file, compiled and finally linked to the applications binary. This files will be automatically handled by the IWebserverPlugin. That means, that
a request of a static file never will reach the applications coded. Instead, the IWebserverPlugin will send the file to the webserver who will send it to the client that requested the file. So for each incomming GET request, the
IWebserverPlugin will at first look at the list of static files, if the request is for one of them. If not, the UWebserverPlugin::WebserverHttpListenResult() function will be called, so that the application can respond to that request
or deny it. Note that the static files name also can include subfolder. So a static file can be linked to the applications binary as "images/icon.png", it can be accessed by a client at "http://<server-address>/<applications-root>/images/icon.png".
File information
Functions
Functions to initialize
extern IWebserverPluginProvider * CreateWebserverPluginProvider();
Overview
This function must be used to create an instance of the IWebserverPluginProvider. With that instance, an IWebserverPlugin instance can be created.
CreateWebserverPluginProvider
Return value
The IWebserverPluginProvider instance. That instance can be freed as soon as it no longer is used by calling the C++ delete operator.
Helper functions
inline wsr_type_t GetResponseTypeForFileName(const char * fileName);
inline const char * WSCancelTypeToStr(wsr_cancel_type_t c);
inline const char * WSPCloseReasonToStr(wsp_close_reason_t cr);
inline const char * WSWebdavResultToStr(ws_webdav_result_t r);
Overview
This functions are helper function to make development life a little bit easier. While GetResponseTypeForFileName() iterrates trough the list of resource types to get the resource type for a given file prefix, the other functions
are for mapping an enum type to a human readable string. That helps especially for debugging purposes.
GetResponseTypeForFileName
Parameters
| const char * filename | The filename to figure out the type to return for that request. That type will be written in the answers HTTP header. |
Return value
The wsr_type_t resource type to set for a GET request. The response type will be returned depending on the file prefix. See wsr_type_t for more information.
WSCancelTypeToStr
Parameters
| wsr_cancel_type_t c | The wsr_cancel_type_t value to convert to a string. |
Return value
The given wsr_cancel_type_t value as human readable string, so that it can be written to a log instead of only a number value.
WSPCloseReasonToStr
Parameters
| wsp_close_reason_t cr | The wsp_close_reason_t value to convert to a string. |
Return value
The given wsp_close_reason_t value as human readable string, so that it can be written to a log instead of only a number value.
WSWebdavResultToStr
Parameters
| ws_webdav_result_t r | The ws_webdav_result_t value to convert to a string. |
Return value
The given ws_webdav_result_t value as human readable string, so that it can be written to a log instead of only a number value.
Classes
IWebserverPluginProvider
class IWebserverPluginProvider {
public:
virtual ~IWebserverPluginProvider() {}
virtual class IWebserverPlugin * CreateWebserverPlugin(class IIoMux * const iomux,
class ISocketProvider * localSocketProvider,
class UWebserverPlugin * const user,
const char * webserverAddress,
const char * appWebRoot,
class IInstanceLog * const log);
};
Overview
The IWebserverPluginProvider is used to create an instance of IWebserverPlugin. Multiple instances of IWebserverPlugin can be created, but generally only one IWebserverPlugin is needed for each AppInstance. The created IWebserverPlugin
does not depend on the IWebserverPluginProvider it had been created from. So the IWebserverPluginProvider instance can be deleted as soon as no longer needed.
Public functions
CreateWebserverPlugin
Creates the IWebserverPlugin instance. The application is responsible to free the instance when no longer needed. This must not be done before calling IWebserverPlugin::Shutdown() and
receiveing the UWebserverPlugin::WebserverPluginShutdownComplete() callback.
Parameters
| class IIoMux * const iomux | The IIoMux instance the IWebsocketPlugin instance will be registered to. |
| class ISocketProvider * localSocketProvider | The ISocketProvider instance that will be used to create a local socket. |
| class UWebserverPlugin * const user | The IIoMux instance the IWebsocketPlugin instance will be registered to. |
| const char * webserverAddress | The address of the webserver. Will be passed to the application from the manager. |
| const char * appWebRoot | The root of the app inside the web structure. Can not be the root of the system ("/"), as well as not a folder already used by an other app. |
| class IInstanceLog * const log | The IInstanceLog instance used for loging purposes. |
Return value
The IWebserverPlugin instance It must be freed by the C++ operator delete, if no longer be used.
IWebserverPlugin
class IWebserverPlugin {
public:
virtual ~IWebserverPlugin() {};
virtual void SendCertificate(const char * password, const byte * certBuf, size_t certLen, const char * hostName = nullptr, UWebserverPlugin * user = nullptr);
virtual void HttpListen(const char * path = nullptr, UWebserverPlugin * user = nullptr, const char * authUser = nullptr, const char * authUserPwd = nullptr, const char * staticFilePrefix = nullptr);
virtual void HttpListen(const char * path, UWebserverPlugin * user, bool dynamicAuth, const char * staticFilePrefix = nullptr);
virtual void PassthroughListen(const char * path = nullptr, UWebserverPlugin * user = nullptr);
virtual void WebsocketListen(const char * path = nullptr, UWebserverPlugin * user = nullptr);
virtual void SetAuthConfig(const char * path, const char * authUser = nullptr, const char * authPwd = nullptr);
virtual void SetAuthConfig(const char * path, bool enableDynAuth);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void Redirect(const char * newDestination);
virtual void Accept(class UWebserverGet * const user);
virtual void Accept(class UWebserverPost * const user);
virtual void Accept(class UWebserverPut * const user);
virtual void Accept(class UWebserverPassthrough * const user);
virtual void Accept(class UWebserverPropfind * const user);
virtual void Accept(class UWebserverMove * const user);
virtual void Accept(class UWebserverMkCol * const user);
virtual void Accept(class UWebserverCopy * const user);
virtual void Accept(class UWebserverDelete * const user);
virtual void Accept(class UWebserverLock * const user);
virtual void Accept(class UWebserverUnlock * const user);
virtual void Accept(class UWebserverProppatch * const user);
virtual void Accept(class UWebserverOptions * const user);
virtual void WebsocketAccept(class UWebsocket * user);
virtual void RequestUserPasswordResult(dword connectionID, const char * user, const char * password);
virtual void Close();
};
Overview
The IWebsocketPlugin is the interface used by an app to hook itself into the webserver of the innovaphone App Platform. Doing so allows the app to receive HTTP requests (including WebDav) as well as Websocket requests. This is primarily
used to provide and communicate with a JavaScript UI. However, it can be used for HTTP communication beside this as well.
To receive request, an application first must call one of the listen functions of IWebserverPlugin. The functions can be called multiple times to listen to different paths, but only once per path. An exception is the difference of the listen
call. So WebsocketListen() can be called for a path that alrady had been used for HttpListen(). But be carefull with the order the listen calls will be made. When an application calls Listen() (HttpListen(), WebsocketListen() or PassthroughListen()) more than
once to listen to different paths, this calls are handled asynchronious. That means, that after the first HttpListen() had been handled, an incomming connection can already accepted before the second HttpListen() had been handled by the Webserver
(same for WebsocketListen() and PassthroughListen()). So if the second one goes to a subpath, that can lead to wrong listen result calls.
For example, an applications whants to listen to "/myapp" and "/myapp/image". But because a listen to "/myapp" also leads for a HttpListenResult if "/myapp/images/myimage.png" is requested, but "/myapp/images" is not yet registerd
for listen, HttpListenResult will be called with a path and registeredPathForRequest value that the application won't expect. To prevent that, the HttpListen() must be called in opposide order. So in our example,
at first HttpListen("/myapp/images") should be called before HttpListen("/myapp"). For passthrough (see below), that problem doesn't exist. Because To now more about the listen result function, see UWebserverPlugin.
The Webserver itself will resolve a request and redirects it in a prepared maner to the IWebsocketPlugin resbonsible for that request. So the App generally don't need to handle any HTTP protocoll (as long as the IWebsocketPlugin is not used
for passthrough, whicht gives full control over the protocoll to the app). Generally, an incomming request will lead to an aproriate UWebserverPlugin::WebserverPlugin*ListenResult() (while * can be Http, Websocket or Passthrough). The only
exception is an incomming GET request. In that case, the IWebserverPlugin at first will look for static files linked to the app, that can fulfill the request. If found, the file will be send to the Client and therefore the request will be respondet from
the IWebserverPlugin internally. The application won't be notified. So if an app only whants to provide static files, there is no need to implement an UWebserverPlugin::WebserverPluginHttpListenResult().
A path can be registered to be password protected. This can be either an fixed user and password, that will not change during the applications running time, or in a dynamic way, which means that for each request the webserver asks the
application for the password of the user that tries to access. It is alos possible to only password protext a subfolder, by calling a IWeberverPlugin::HttpListen() to the apps root without password information and calling it again for a subfolder,
telling that that subfolder needs authentication. Authentication is only supportet for HTTP listen, not for websocket or pass through.
While all request will be handled by the webserver itself, so that an application has no need to handle the HTTP protocol, it can be necessary some times to have control on what's going on. So an application can also call
IWebserverPlugin::PassthroughListen(), which will end up in an UWebserverPlugin::WebserverPluginPassthroughListenResult() for each incoming request. The difference is, that the request will be passed through to the app, ans so the app
needs to parse the HTTP header and buld up a correct HTTP header for response (also handle websocket or whole authentication stuff, if needed). Parsing and creating a HTTP header can be done with the
HTTPLib::HTTPHeader and HTTPLib::HTTPParser classes.
Logging
To enable logging for IWebserverPlugin, the flag LOG_WEBSERVER_TRAFIC must be set in the managers diagnostic settings.
Public functions
HttpListen (overloaded)
Starts to listen to incomming HTTP requests. If an incomming request as a GET request and can be resolved with to the app linked static files, the request will be handled internally. Else the application will receive a callback to
response or cancel the request. And application must call the function at least for the appications root (with path = nullptr), even if only whant to provide static files.
Parameters
| const char * path | (Default nullptr) The path to listen to. Note that that path always will be under the applications web root, defined when creating the IWebserverPlugin. If this value is nullptr, the root will be used. |
| UWebserverPlugin * user | (Default nullptr) The user to inform about an incoming request. This helps to have different UWebserverPlugin instances for different path to list. If set to nullptr, the same user as passed to IWebserverPluginProvider::Create() will be used (which hovewer is the default user). |
| const char * authUser | (Default nullptr) The user to use for authentication. If not is null, authentication for the given pass will be activated. |
| const char * authPassword | (Default nullptr) The password to use for authentication. |
| const char * staticFilePrefix | (Default nullptr) If not is nullptr, the value given will be used as prefix for static files. This can also include '/' to simulate an other path. |
Callbacks
On success, an incoming HTTP request will lead to a callback of UWebserverPlugin::WebserverPluginHttpListenResult(), if the request is not a get request and, in that case, can't be resolved with an static file linked to the applications binary.
If an error occurres, USocket::SocketShutdown() will be called. Details of that error can be found inside the log, if logging is activated. Reason can be one of the following values:
| WSP_REGISTER_PATH_INVALID | The path given to register is invalid. |
| WSP_PATH_ALREADY_REGISTERD | An other application already is listening to that path. |
| WSP_ADDRESS_INVALID | The address to connect to the webserver is invalid. |
Remarks
This function is overloaded (see below).
Calling IWebserverPlugin::HttpListen() more than once to the same path will lead to an assertion. If tryed to called it for a path already registered by an other application, the listen will be rejected by the webserver.
However, the connection to the connection will be established the fist time, one of the IWebserverPlugin::*Listen() functions. The listen calls will be cached, so if the connection get lost, the IWebserverPlugin will connect
to the webserver again and also makes the listen calls again, too.
HttpListen (overloaded)
This overloaded version does the same as described above. The difference is, that this version will be used to activate dynamic authentication, which means that the webserver asks the application for a password of a user that
tries to connect. If the flag dynamicAuth is set to false, the function acts like calling the function above with authUser set to nullptr.
Parameters
| const char * path | The path to listen to. Note that that path always will be under the applications web root, defined when creating the IWebserverPlugin. If this value is nullptr, the applications root will be used. |
| UWebserverPlugin * user | The user to inform about an incoming request. This helps to have different UWebserverPlugin instances for different path to list. If set to nullptr, the same user as passed to IWebserverPluginProvider::Create() will be used (which hovewer is the default user). |
| bool dynamicAuth | If true, dynamic authentication will be activated. That means, that the Webserver asks the application for the password for a user that tries to authenticate. |
| const char * staticFilePrefix | (Default nullptr) If not is nullptr, the value given will be used as prefix for static files. This can also include '/' to simulate an other path. |
Callbacks
On success, an incoming HTTP request will lead to a callback of UWebserverPlugin::WebserverPluginHttpListenResult(), if the request is not a get request and, in that case, can't be resolved with an static file linked to the applications binary.
If a user tries to authenticate, the Webserver asks the app for the password of the user who tries to authenticate by calling UWebserverPlugin::WebserverPluginRequestUserPassword(). The password must be sent using
IWebserverPlugin::RequestUserPasswordResult() (see below).
If an error occurres, USocket::SocketShutdown() will be called. Details of that error can be found inside the log, if logging is activated. Reason can be one of the following values:
| WSP_REGISTER_PATH_INVALID | The path given to register is invalid. |
| WSP_PATH_ALREADY_REGISTERD | An other application already is listening to that path. |
| WSP_ADDRESS_INVALID | The address to connect to the webserver is invalid. |
Remarks
This function is overloaded (see below).
Calling IWebserverPlugin::HttpListen() more than once to the same path will lead to an assertion. If tryed to called it for a path already registered by an other application, the listen will be rejected by the webserver.
However, the connection to the connection will be established the fist time, one of the IWebserverPlugin::*Listen() functions. The listen calls will be cached, so if the connection get lost, the IWebserverPlugin will connect
to the webserver again and also makes the listen calls again, too.
PassthroughListen
An appliction can register itself for passthrough. Y request to that path, whatever kind of request, will be completly redirected to the appliaction. That means, that the application is responsible for handling the HTTP header (the incoming
and outgoing) as well as all the other HTTP protocoll relarted stuff. The Webserver itself does nothing than passing through the bytestream between the client and the application. This can be done with the help of the
HTTPLib::HTTPHeader and HTTPLib::HTTPParser classes. PassthroughListen() only should be used if it is really necessary, generally
it is recommended to let the Webserver itself handle all of the HTTP related stuff.
Parameters
| const char * path | The path to listen to for passthrough. Note that that path always will be under the applications web root, defined when creating the IWebserverPlugin. If this value is nullptr, the applications root will be used. |
| UWebserverPlugin * user | The user to inform about an incoming request. This helps to have different UWebserverPlugin instances for different path to list. If set to nullptr, the same user as passed to IWebserverPluginProvider::Create() will be used (which hovewer is the default user). |
Callbacks
On success, an incoming request will lead to a callback of UWebserverPlugin::WebserverPluginPassthroughListenResult().
If an error occurres, USocket::SocketShutdown() will be called. Details of that error can be found inside the log, if logging is activated. Reason can be one of the following values:
| WSP_WEBSOCKET_PATH_INVALID | The path given to listen to websocket connection is invalid. |
| WSP_WEBSOCKET_PATH_ALREADY_LISTENING | An other application already is listening to that path. |
| WSP_ADDRESS_INVALID | The address to connect to the webserver is invalid. |
Remarks
Pathrough always will be handled with priority. So if IWebserverPlugin::HttpListen() and IWebserverPlugin::PassthroughListen() will be called with the same path, only the passthrough will be handled.
WebsocketListen
Listens for incomming webocket connection to the given path. WebsocketListen() can be called for a path that had been used for HTTPListen() before.
Parameters
| const char * path | The path to listen to for websocket conenctions. Note that that path always will be under the applications web root, defined when creating the IWebserverPlugin. If this value is nullptr, the applications root will be used. |
| UWebserverPlugin * user | The user to inform about an incoming websocket request. This helps to have different UWebserverPlugin instances for different path to list. If set to nullptr, the same user as passed to IWebserverPluginProvider::Create() will be used (which hovewer is the default user). |
Callbacks
On success, an incoming Websocket request will lead to a callback of UWebserverPlugin::WebserverPluginWebsocketListenResult().
If a user tries to authenticate, the Webserver asks the app for the password of the user who tries to authenticate by calling UWebserverPlugin::WebserverPluginRequestUserPassword().
If an error occurres, USocket::SocketShutdown() will be called. Details of that error can be found inside the log, if logging is activated. Reason can be one of the following values:
| WSP_WEBSOCKET_PATH_INVALID | The path given to listen to websocket connection is invalid. |
| WSP_WEBSOCKET_PATH_ALREADY_LISTENING | An other application already is listening to that path. |
| WSP_ADDRESS_INVALID | The address to connect to the webserver is invalid. |
Remarks
It is allowed to use the same path for IWebserverPlugin::WebsocketListen() as used for IWebserverPlugin::HttpListen().
SetAuthConfig (overloaded)
Must be called if the configuration for authentication of a path should be changed. The changes will become active immediately. This overloaded version will be used to enable static authentication with the given username and password. So multiple calls to that function can be used to change the username or password, too. Setting them both to nullptr, will deactivate authentication for the given path, independent whether if static or dynamic authentication is currently active.
Parameters
| const char * path | The path to listen to change the authentication configuration for (without the app web root). If this is nullptr, "/" or "", the app webroot will be used. |
| const char * authUser | (Default: nullptr) The user name to use for authentication. If this value is not nullptr, the authentication will be enabled or changed to static authentication. |
| const char * authPwd | (Default: nullptr) The password to use for authentication. |
Callbacks
The call to that function will lead to a UWebserverPlugin::SetAuthConfigResult() callback. The result of the action will be reported with one of the ws_update_auth_result_t values.
Remarks
This version activates (or changes the parameters for) static authentication. It also only can be called for a path that had been passed to a previous HTTPListen() call.
SetAuthConfig (overloaded)
Must be called if the configuration for authentication of a path should be changed. The changes will become active immediately. This overloaded version will be used to enable dynamic authentication. Passing false as enableDynAuth, will deactivate authentication for the given path, independent whether if static or dynamic authentication is currently active.
Parameters
| const char * path | The path to listen to change the authentication configuration for (without the app web root). If this is nullptr, "/" or "", the app webroot will be used. |
| bool enableDynAuth | True, to enable or change to dynamic authentication. If false, authentication will be deactivated. |
Callbacks
The call to that function will lead to a UWebserverPlugin::SetAuthConfigResult() callback. The result of the action will be reported with one of the ws_update_auth_result_t values.
Remarks
SetAuthConfig() only can be called for a path that had been passed to a previous HTTPListen() call. However, it also can be used to switch from dynamic authentication to static authentication, if needed.
SendCertificate
The Webserver supports TLS encrypted connections. This function let define the certficate to use. Generally there is no need for an application to call this function, becuse the certificate will be set by the Manager.
Parameters
| const char * password | The password to use with the certificate. |
| const byte * certBuf | The buffer with the certificate to send. Must not be nullptr. |
| size_t certLen | The length of the certificate. |
| const char * hostName | Reserved for later use, always should be set to nullptr. |
| UWebserverPlugin * user | The user to inform the result. This helps to have different UWebserverPlugin instances. If set to nullptr, the same user as passed to IWebserverPluginProvider::Create() will be used (which hovewer is the default user). |
Callbacks
On success, an incoming request will lead to a callback of UWebserverPlugin::WebserverPluginSendCertificateResult().
If an error occurres, USocket::SocketShutdown() will be called. Details of that error can be found inside the log, if logging is activated. :
| WSP_ADDRESS_INVALID | The address to connect to the webserver is invalid. |
Accept
If an incomming request should be accepted, one of the IWebserverPlugin::Accept() functions must be called. For each request an instance of one of the following users must be passed (depending on request type):
- UWebserverGet
- UWebserverPost
- UWebserverPut
- UWebserverPassthrough
- UWebserverPropfind
- UWebserverMove
- UWebserverMkCol
- UWebserverCopy
- UWebserverDelete
- UWebserverLock
- UWebserverUnlock
- UWebserverProppatch
- UWebserverOptions
The application must create a class derived from one of the users above and implement the necessary functions. If passing nullptr instead an instance of one of that classes, the request will be cancleed (which will be
the same behaviour as calling cancel with WSP_CANCEL_NOT_FOUND).
Parameters
| User instance * user | The instance of one the above users. That user will be responsible to handle the request. If nullptr, the request will be handled with reason WSP_CANCEL_NOT_FOUND. |
Callbacks
After calling Accept() with a valid user instance, the *RequestAcceptComplete() callback of the given user will be called (e. G. UWebserverGet::WebserverGetRequestAcceptComplete()). See the documentation for that user classes for more details.
Remarks
IWebserverPlugin::Accept() must be called inside the UWebserverPlugin::WebserverPluginHttpListenResult() or UWebserverPlugin::WebserverPassthroughListenresult(). If the request should not be accepted, IWebserverPlugin::Cancel() must be called.
To accept an incomming Websocket request, IWebserverPlugin::WebsocketAccept() must be called.
Calling IWebserverPlugin::Accept() with an instance of one of the user classes that not will correspond to the accept will lead to an assertion.
WebsocketAccept
If a websocket request comes in, it can be accepted using the WebsocketAccept() function. (To deny, call Cancel()). When accepting, an instance of a class derived from UWebsocket must be passed. This instance will be responsible for the websocket
connections. See UWebsocket for details. If nullptr will be passed to WebsocketAccept(), the request will be denied in the same way as calling IWebserverPlugin::Cancel().
Parameters
| UWebsocketUser * user | The instance of one the users to handle the websocket communication, that will be responsible to handle the request. If nullptr, the request will be denied. |
Callbacks
After calling Accept() with a valid user instance, the UWebsocket::WebsocketAcceptComplete callback of that user will be called.
Remarks
IWebserverPlugin::WebsocketAccept() must be called inside the UWebserverPlugin::WebserverPluginWebsocketListenResult(). If the request should denied, IWebserverPlugin::Cancel() must be called.
Cancel
This function will be used to deny an incomming request.
Parameters
| wsr_cancel_type_t reason | The reason why the request had been canceled. See wsr_cancel_type_t for more infos. |
Remarks
This function must be called from inside of one of the *ListenResult() functions.
Like Accept() (and WebsocketAccept()), Cancel() will be used to deny each type of request, including websocket.
Redirect
An incomming request can not only be accepted or denied, it can also be redireted to an other location. Redirecting using this function is a temporary redirect. That means, that a HTTP conform client will automatically went to the new place, until
the browser will be started again.
Parameters
| const char * newDestination | The destination to redirect to. Can be a relative or absolut path. For an absolute path, the value muast start with "http://". |
Remarks
Like Accept() and Cancel(), this function must be called inside the *ListenResult() function (e. G. UWebserverPlugin::WebserverPluginHttpListenReuslt()).
Redirection is not supported for Websocket requests. Calling IWebserverPlugin::Redirect() for a websocket request will lead to an assertion.
RequestUserPasswordResult
When dynamic authentication had ben activated (see HttpListen() above) and the Webserver asks for a users password, IWebserverPlugin::RequestUserPasswordResult() must be called. This funtion can be called outside from
UWebserverPlugin::WebserverPluginRequestUserPassword(), so reading the password from an other source like a database is possible. Note that the client needs to wailt until the app calls RequestUserPasswordResult().
Parameters
| dword connectionID | The ID of the connection authentication request comes from. Must be the same id as received in UWebserverPlugin::WebserverPluginRequestUserPassword(). If the
password can not be send directly inside the request function, the application must save the connection id to response later. |
| const char * user | The user that requested the authentication. Must be the same as received in UWebserverPlugin::WebserverPluginRequestUserPassword(). If the
password can not be send directly inside the request function, the application must save the user name to response later. If the user is denied by the application, user can
set to nullptr for the response. |
| const char * password | The password for that user. If user is set to nullptr, tha value given to password will be ignored. If password is set to nullptr, no password will be used for authentication. |
Remarks
If the connection id and user name are not the same as passed to UWebserverPlugin::WebserverPluginRequestUserPassword(), the webserver will deny the request (like setting user to nullptr).
Close
Closes the IWebserverPlugin instance. The application must wait until UWebserverPlugin::WebserverPluginClose() had been closed with lastUser set to true, before freeing the IWebserverPlugin instance. See UWebserverPlugin for more details.
Remarks
After closed, each still active user passed to one of the functions that accept an aditional UWebserverPlugin instance, will receife a UWebserverPlugin::WebserverPluginClose() callback. It is guaranteed, that the main user will
be the last one informed. The lastUser flag helps to identify that case.
UWebserverPlugin
class UWebserverPlugin {
public:
virtual ~UWebserverPlugin() {}
virtual void WebserverPluginClose(IWebserverPlugin * plugin, wsp_close_reason_t reason, bool lastUser)
{
if (lastUser) delete plugin;
}
virtual void WebserverPluginHttpListenResult(IWebserverPlugin * plugin, ws_request_type_t requestType, char * resourceName, const char * registeredPathForRequest, ulong64 dataSize)
{
plugin->Cancel(WSP_CANCEL_NOT_FOUND);
}
virtual void WebserverPluginPassthroughListenResult(IWebserverPlugin * plugin, char * resourceName, const char * registeredPathForRequest, ulong64 dataSize)
{
plugin->Cancel(WSP_CANCEL_NOT_FOUND);
}
virtual void WebserverPluginWebsocketListenResult(IWebserverPlugin * plugin, const char * path, const char * registeredPathForRequest, const char * host)
{
plugin->WebsocketAccept(nullptr);
}
virtual void WebserverPluginConnected() {}
virtual void WebserverPluginSendCertificateResult(IWebserverPlugin * plugin, byte * certBuffer) {}
virtual void WebserverPluginRegisterPathResult(IWebserverPlugin * plugin, const char * pathName, wsp_path_type_t pathType) {}
virtual void WebserverPluginRequestUserPassword(IWebserverPlugin * plugin, dword connectionID, char * resourceName, const char * registeredPathForRequest, const char * host, const char * user) { ASSERT(false, "UWebserverPlugin::WebserverPluginRequestUserPassword() not implemented!"); }
virtual void SetAuthConfigResult(const char * path, ws_update_auth_result_t result) {}
};
Overview
Each action needed to be redirected to the applicationm the IWebserverPlugin instrance will call one fo the UWebserverPlugin functions. So an application that is going to use the Webserver Plugin must provide a subclass of
UWebserverPlugin and implement what is needed. UWebserverPlugin is used to handle incomming requests (if not a GET request handled by static files), accept requests and handle some other details.
Public functions
WebserverPluginHttpListenResult
Will be called after calling IWebserverPlugin::HttpListen() and receiving a HTTP request. The request must be canceld or accepted inside this function. If the function will return without accepting or canceling the
request, an assertion will be thrown. To accept the request, IWebserverRequest::Accept() must be called, passing an UWebserver* handler instance combining with the request.
Parameters
| IWebserverPlugin * plugin | The calling IWebserverPlugin instance |
| ws_request_type_t requestType | The type of the request. See ws_request_type_t for details. |
| char * resourceName | The resource requested. The resource can include a relative path, with the given registeredPathForRequest as root. |
| char * registeredPathForRequest | The registered path for that request. |
| ulong64 dataSize | The size of the data comming with the request, if the kind of request can deliver data (e. g. POST). |
Callbacks
If the incomming request had been accepted, the WebserverPluginAcceptComplete of the user passed to accept will be called.
Remarks
Valid users for an HTTP request to pass to IWebserverPlugin::Accept() are:
- UWebserverGet
- UWebserverPost
- UWebserverPut
- UWebserverPassthrough
- UWebserverPropfind
- UWebserverMove
- UWebserverMkCol
- UWebserverCopy
- UWebserverDelete
- UWebserverLock
- UWebserverUnlock
- UWebserverProppatch
- UWebserverOptions
WebserverPluginPassthroughListenResult
Will be called after calling IWebserverPlugin::PassthroughListen() and receiving a passthrough request. The request must be canceld or accepted inside this function. If the function will return without accepting or canceling the
request, an assertion will be thrown. To accept the request, IWebserverRequest::Accept() must be called, passing an UWebserverPassthrough instance. Note that if the application listens for passthrough, it will be responsible
to handle the HTTP request by itself.
Parameters
| IWebserverPlugin * plugin | The calling IWebserverPlugin instance |
| char * resourceName | The resource requested. The resource can include a relative path, with the given registeredPathForRequest as root. |
| char * registeredPathForRequest | The registered path for that request. |
| ulong64 dataSize | The size of the data comming with the request. This data must be be read with IWebserverPassthrough::Recv() and includes the whole HTTP header of the request. |
Callbacks
If the incomming request had been accepted, the WebserverPluginAcceptComplete of the user passed to accept will be called.
WebserverPluginWebsocketListenResult
Will be called after calling IWebserverPlugin::WebsocketListen() and receiving a websocket request. The request must be canceld or accepted inside this function. If the function will return without accepting or canceling the
request, an assertion will be thrown. To accept the request, IWebserverRequest::Accept() must be called, passing an UWebsocket instance.
Parameters
| IWebserverPlugin * plugin | The calling IWebserverPlugin instance |
| const char * path | The path for the request. However, even if it is called "path", it can include a filename, too. Depending on what had been passed to IWebserver::WebsocketListen(). |
| const char * registeredPathForRequest | The registered path for that request. |
| const char * host | The host of the request. |
Callbacks
If the incomming request had been accepted, the WebserverPluginWebsocketAcceptComplete of the user passed to accept will be called.
WebserverPluginConnected
Will be called after calling IWebserverPlugin::Connect() and after the connection had been established. It will be e good idea to call the IWebsocketPlugin::*Listen() after the connection had been established, but
it can bee called before receiving the WebserverPluginConnected() callback either.
WebserverPluginClose
Will be called after the IWebserverPlugin had been closed. Note that when the WebserverPlugin uses the connection (because the websever is down), it is going to reconnect until the connection can be established again. After closing,
the IWebserverPlugin Instance should be released.
Parameters
| IWebserverPlugin * plugin | The calling IWebserverPlugin instance |
| wsp_close_reason_t reason | The reason why the plugin had been closed. See wsp_close_reason_t for more details. |
| bool lastUser | If true, the user that receivces that callback is the last user, so that the instance can be deleted. |
Remarks
Because the IWebserverPlugin::*Listen() function can be called with multiple users, each user given to that functions will receive teh WebserverPluginClose() callback with lastUser set to false. Except the last user which
is the user given when creating the plugin. This user will receive the callback with lastUser set to true. In that case it is gauranteed, that all other users already had been informed and no more WebserverPluginClose()
call will be made. So the IWebserverPlugin instance can be deleted. Never delete the instance while lastUser is false!
WebserverPluginSendCertificateResult
The IWebserverPlugin can be used to send a certificate to the Webserver, that will be used for TLS connections. After sucessfully sent, this function will be called.
Parameters
| IWebserverPlugin * plugin | The calling IWebserverPlugin instance |
| byte * certBuffer | The buffer with the certificate sent. |
Remarks
Normally, the AppPlatform Manager will send the certificate to the webserver, so there is no need for an app to use the mechanism to set a certificate.
WebserverPluginRegisterPathResult
When calling one of the Listen functions of IWebserverPlugin, the path given to that function will be registerd inside the webserver. This process will lead to the WebserverPlugin RegisterPathResult() call.
An application can watch to the result of the registration process (if wanted) by implementing that callback function.
Parameters
| IWebserverPlugin * plugin | The calling IWebserverPlugin instance |
| const char * pathName | The registered path name, the same as given to one of the listen functions. |
| wsp_path_type_t pathType | The type of the registered path. The value depends on the called listen function. See wsp_path_type_t for more details. |
WebserverPluginRequestUserPassword
The IWebserverPlugin supports two ways for authentication: the static authentication (that is giving the user name and password while listening to the a path), and the dynamic way where the Webserver asks the IWebserverPlugin
for the user name and password for each request. This will be done with this callback. The user name an password must be returned to the Webserver by calling IWebserverPlugin::RequestUserPasswordResult().
Parameters
| IWebserverPlugin * plugin | The calling IWebserverPlugin instance |
| dword connectionID | The id of the connection that whants to authenticate. This ID must be given (together with the user name) to IWebserverPlugin::RequestUserPasswordResult() for answering the authentication request. |
| char * resourceName | The resource the needs to authenticate. The resource can include a relative path, with the given registeredPathForRequest as root. |
| const char * registeredPathForRequest | The registered path for the request. |
| const char * host | The host that tries to acces the resource. |
| const char * user | The user that tries to authenticate. Must be given (together with the connection id) to IWebserverPlugin::RequestUserPasswordResult() for answering the authentication request. |
Remarks
The authentication request can be responded outside of this function. This comes in handy if e. g. the user information must be read from the database, first. The application only need to take care of sending the correct connection id with the
user name given for the request.
SetAuthConfigResult
Will be called after the webserver has changed the authentication configuration because of a previous call to IWebserverPlugin::SetAuthConfig().
Parameters
| const char * path | The path the configuration needed to be changed for ("/" for the apps web root). Will always be the same path as used for the previous SetAuthConfig() call. |
| ws_update_auth_result_t result | The result of the config change. See the ws_update_auth_result_t enum for details. |
IWebserverGet
class IWebserverGet {
public:
virtual ~IWebserverGet() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual const char * GetETag();
virtual ulong64 GetRangeCount();
virtual IWebserverGetRange * GetRange(size_t idx);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void SetTransferInfo(wsr_type_t resourceType, ulong64 dataSize, wsr_flags_t flags = WSP_FLAG_NONE, const char * etag = nullptr);
virtual void SetTransferRange(ulong64 rangeStart, ulong64 rangeEnd);
virtual void ForceDownloadResponse(const char * fileName = nullptr);
virtual void Send(void * buffer, size_t len);
virtual void Close();
};
Overview
After accepting an incoming GET request, UWebserverGet::WebserverGetRequestAcceptComplete() will be called with the IWebserverGet instance to use to answer the request. The IWebserverGet intercace is all
that is needed to response the GET request. The instance is only valid for one request, and each request has it's own IWeberverGet instance. After sending the response, the IWebserverGet instance must be closed
to tell the Webserver, that the response had been completed.
Public functions
GetResourceName
Returns the name of the requested resource. That name inclides the path below the registered path the request was for. So if the registered path is "/images" and the request goes to "/images/ui/buttons/ok.png", GetResourceName()
will return "/ui/buttons/ok.png".
Return value
The resource requested as const string.
GetRegisteredPathForRequest
Returns the registered path the request was for. So if the registered path is "/images" and the request goes to "/images/ui/buttons/ok.png", GetRegisteredPathForRequest() will return "/images".
Return value
The registered path of the request as const string.
GetETag
Return the ETag, if there is any. ETag will be used for the caching mechanism of the HTTP clients. The static files will send an ETag (which is the MD5 checksum of the file) to help the browser indendicate, whether a file had been changed or not. The
This also can be done for a dynamic file by setting an etag (which must not be a MD5 checksum) and comparing it with the one send by the browser on further requests.
Return value
The Etag as const string.
Remarks
The default validity for a file with browser caching enabled is 5 minutes.
GetRangeCount
If the HTTP client only requests a part of a file, he will send ranges to define what part. GetRangeCount() returns the number of ranges available for that requst. The ranges values will be retunred by GetRange() (see below). The application
must only return the data for the requested ranges.
Return value
The number of ranges for the request. If 0, there are no ranges for that request. In that case, the application must return the whole file.
GetRange
Returns the range with teh given index. See IWebserverGetRange for details.
Parameters
| size_t idx | The index of the range to get, zero based. Must not exceed IWebserverGet::GetRangeCount() - 1. |
Return value
An IWebserverGetRange instance holding the range informations.
Remarks
The returned IWebserverGetRange instance is managed by the IWebserverGet instance. The data hold by IWebserverGetRange will be valid until the next time GetRange() will be called. If the range needed to be saved
for later use, the application must store the data elsewhere.
You must not free the IWebserverGetRange instance returned by IWebserverGet.
Cancel
Sometimes an application can not know if a request should be accepted or now at the moment, the request leads to a listen result. For that cases, the request can still be cancled inside the UWebserverGet instance
by calling IWebserverGet::Cancel(). However, this function can also be used to cancel an already started byte transfer for the response. This comes in handy, when there is need to cancel a chunk encoded response or
even a response with kown content length.
Parameters
| wsr_cancel_type_t reason | The reason for the cancel. See wsr_cancel_type_t for more details. |
Remarks
Cancel() will call Close() after sending the informations to the Webserver.
SetTransferInfo
Before responding for a GET request, the type of the request must set first by calling SetTransferInfo().
Parameters
| wsr_type_t resourceType | The type of the reosurce the application is going to send. Dis should combine with the type of resource requested. The helper functon
GetResponseTypeForFileName can be used to get the right resource type depending on the resource sufix. |
| ulong64 dataSize | The data size of the requests data. If unkown, the application must used chunked encoding by setting dataSize to WS_RESPONSE_CHUNKED. |
| wsr_flags_t flags | (Default WSP_FLAG_NONE)Optional, additional flags. See wsr_flags_t for details. |
| const char * etag | (Default nullptr) An optional etag used for caching purposed of an HTTP client. |
Remarks
When passing an etag value, the HTTP clients caching mechanism will be activated. The default validity for a file with browser caching enabled is 5 minutes. So in that time, the HTTP client won't ask again for the file but loads
it from it's local cache. The time period is fixed and cannot be changed.
SetTransferRange
When the HTTP client requests a range only, the response must define the range sent.
Parameters
| ulong64 rangeStart | The start of the range. |
| ulong64 rangeEnd | The end of the range. |
Remarks
The values of rangeStart and rangeEnd depends on the requested range. See IWebserverGetRange for details.
ForceDownloadResponse
Generally, when requesting a file with the GET request, the HTTP client will save the file under the requested name. Somethimes there is need to save the file under an other name. This can be realized
using ForeceDownloadResponse() to set the file name.
Parameters
| const char * fileName | (Default nullptr) The filename the HTTP client should use. If set to nullptr, the same filename as requested will be used. That's practically the same as
not calling ForceDownloadResponse(). |
Send
Sends the given data. The number of bytes that will be send must be the same as given to SetTransferInfo() (unless WS_RESPONSE_CHUNKED has passed as dataSize to SetTransferInfo()). If the data the application will send
exceeds WS_MAX_DATA_SIZE, multiple Send() calls must be used.
Parameters
| void * buffer | A pointer to the buffer holding the data to send. |
| size_t len | Then umber of bytes to send. |
Callbacks
After the data had been sent, the UWebserverGet::WebserverGetSendResult() of the user passed to IWenserverPlugin::Accept() will be called.
Remarks
SendTransferInfo() must be called before calling Send() the first time!
Trying to send more than WS_MAX_DATA_SIZE with one send call leads to an assertion.
It is highly recommendet send the next data part after receiving UWebserverGet::WebserverPluginSendResult().
Close
Closes the IWebserverGet interface and with this also finalizes the response. It should be called after the number of bytes passed to SetTransferInfo() or after the last data part for chunked transfer had been sent. An HTTP client
will not realize the end of the transfer and still wait for data, until Close() had been called. If the transfer of the response data should be canceled, IWebserverGet::Cancel() need to be called.
Callbacks
After closing, UWebserverGet::WebserverGetCloseComplete() will be called.
IWebserverGetRange
class IWebserverGetRange {
public:
IWebserverGetRange() {}
virtual ~IWebserverGetRange() {}
enum range_type_t {
RANGE_NONE = 0x00,
RANGE_START_END = 0x01,
RANGE_START_ONLY = 0x02,
RANGE_LAST_BYTES = 0x03
} rangeType;
ulong64 start;
ulong64 end;
};
Overview
Sometimes, a HTTP client will request only a range of a resource. In that case, one or more range informations can be received from the IWebserverGet instance. That informations will be stored inside a IWebserverGetRange and returned
to the app.
Remarks
The applcation must not free an IWebserverGetRange instance received from UWebserverGet::GetRange().
Public fields
start
The start of the range in bytes. The value depends on the range type.
end
The end of the range in bytes. The value depends on the range type.
rangeType
There are different types of ranges defined by this type, which will be one of the vollowing values:
| RANGE_NONE | No range defined. This generally is only for initializing purpose and will never show up in an IWebserverGetRange instance retunred by IWebserverGet::GetRange(). |
| RANGE_START_END | The value of start and end are the byte positions where to start and end the transfer inside the resource. If end is out of range of the resource size, the real end position should be used. |
| RANGE_START_ONLY | The value of start defines the byte position, where to start the transder inside the resource. End will be the rest of data inside the resource. |
| RANGE_LAST_BYTES | The number of the lst bytes of the resource to transfer. With this, the start position is resource end - number of last bytes. |
UWebserverGet
class UWebserverGet {
public:
virtual ~UWebserverGet() {}
virtual void WebserverGetRequestAcceptComplete(IWebserverGet * const webserverGet);
virtual void WebserverGetSendResult(IWebserverGet * const webserverGet);
virtual void WebserverGetCloseComplete(IWebserverGet * const webserverGet);
};
Overview
This is the user for a GET request handler. The application needs to implement the functions below.
Remarks
The request can be responded asynchronously. But the application must take care sending the same number of bytes as defined before start sending
data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the browser
(our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverGet for more details.
Note that the application is responsible for releasing the UWebserverGet instance!
Public functions
WebserverGetRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming GET request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverGet instance for later use.
Parameters
| IWebserverGet * const webserverGet | The calling IWebserverGet instance. |
WebserverGetSendResult
Will be called after a data package send by IWebserverGet::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverGet * const webserverGet | The calling IWebserverGet instance. |
WebserverGetCloseComplete
Will be called after the connection had been called. This can be a result of calling IWebserverGet::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverGet instance.
Parameters
| IWebserverGet * const webserverGet | The calling IWebserverGet instance. |
IWebserverPost
class IWebserverPost {
public:
virtual ~IWebserverPost() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual ulong64 GetDataSize();
virtual bool DataIsChunkEncoded();
virtual void SetTransferInfo(wsr_type_t resourceType, ulong64 dataSize, wsr_flags_t flags = WSP_FLAG_NONE, const char * etag = nullptr);
virtual void ForceDownloadResponse(const char * fileName = nullptr);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void Send(void * buffer, size_t len);
virtual void Recv(void * buffer = nullptr, size_t len = 0);
virtual void Close();
};
Overview
This handler is for handling POST requests. Note that for now the webserver only supports POST requests wich one set of data. If there is a form posted, the application itself need to divide the form data.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetDataSize
Return value
The number of bytes sent with the POST request. The data can be received by calling IWebserverPost::Recv(). If the data is chunke encoded, the size is unkown and 0 will be returned.
DataIsChunkEncoded
Return value
True if the data to receive is chunk encoded, else false.
SetTransferInfo
Before responding for a POST request, the type of the request must set first by calling SetTransferInfo().
Parameters
| wsr_type_t resourceType |
The type of the reosurce the application is going to send. Dis should combine with the type of resource requested. The helper functon
GetResponseTypeForFileName can be used to get the right resource type depending on the resource sufix.
|
| ulong64 dataSize | The data size of the requests data. If unkown, the application must used chunked encoding by setting dataSize to WS_RESPONSE_CHUNKED. |
| wsr_flags_t flags | (Default WSP_FLAG_NONE)Optional, additional flags. See wsr_flags_t for details. |
| const char * etag | (Default nullptr) An optional etag used for caching purposed of an HTTP client. |
Remarks
When passing an etag value, the HTTP clients caching mechanism will be activated. The default validity for a file with browser caching enabled is 5 minutes. So in that time, the HTTP client won't ask again for the file but loads
it from it's local cache. The time period is fixed and cannot be changed.
ForceDownloadResponse
Generally, when requesting a file with the POST request, the HTTP client will save the file under the requested name. Somethimes there is need to save the file under an other name. This can be realized
using ForeceDownloadResponse() to set the file name.
Parameters
| const char * fileName |
(Default nullptr) The filename the HTTP client should use. If set to nullptr, the same filename as requested will be used. That's practically the same as
not calling ForceDownloadResponse().
|
Cancel
Cancels the POST request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverPost::WebserverPostCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverPost intance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client. Before calling Send(), SetTransferInfo() must be called. And if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetTransferInfo().
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverPost::WebserverPostSendResult() of the user passed to IWenserverPlugin::Accept() will be called.
Remarks
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Recv
Receives data sent with the request.
Parameters
| void * buffer | (Default: nullptr) The buffer to store the data to. Must be big enough to be able to receive len bytes of data. |
| size_t len | (Default: 0) The number of bytes to receive. If buffer is not nullptr, len must be > 0. |
Return value
Callbacks
After the data had been read, UWebserverPost::WebserverPostRecvResult() of the user passed to IWebserverPlugin::Accept() will be called. If all data had been read, the WebserverPostRecvResult() will be called with nullptr as buffer and 0 as len.
If buffer is nullptr, UWebserverPost::WebserverPostRecvBuffer() will be called to request the buffer to store the data to.
Remarks
If buffer is nullptr, the IWebserverPost will ask the application for a buffer of a given size when reading the data. This will be realized by the WebserverPostRecvBuffer() callback.
If the data to read is chunk encoded, Recv() should be called (recommended without passing a buffer), until RecvResult() will called with nullptr as buffer and 0 as len. However, this also works for non chunk encoded transfer.
The maximum data to read per Recv() call is WS_MAX_DATA_SIZE.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverPost::WebserverPostCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverPost intance,
because it will no longer be used.
UWebserverPost
class UWebserverPost {
public:
virtual ~UWebserverPost() {}
virtual void WebserverPostRequestAcceptComplete(IWebserverPost * const webserverPost);
virtual void WebserverPostSendResult(IWebserverPost * const webserverPost) {}
virtual void WebserverPostRecvResult(IWebserverPost * const webserverPost, void * buffer, size_t len);
virtual void * WebserverPostRecvBuffer(size_t len) { return nullptr; }
virtual void WebserverPostCloseComplete(IWebserverPost * const webserverPost);
};
Overview
This is the user for a POST request handler. The application needs to implement the functions below. The UWebserverPost instance must be
used to read the data posted and to send a response, if needed.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverPost for more details.
Note that the application is responsible for releasing the UWebserverPost instance!
Public functions
WebserverPostRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming POST request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverPost instance for later use.
Parameters
| IWebserverPost * const webserverPost | The calling IWebserverPost instance. |
WebserverPostSendResult
Will be called after a data package send by IWebserverPost::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverPost * const webserverPost | The calling IWebserverPost instance. |
WebserverPostRecvResult
Will be called after receiving data, initiated through IWebserverPost::Recv().
Parameters
| IWebserverPost * const webserverPost | The calling IWebserverPost instance. |
| void * buffer | The buffer holding the received data. Will be the same as passed to
IWebserverPost::Recv() or returned by UWebserverPost::WebserverPostRecvBuffer().
Will be nullptr if there is no more data to receive. |
| size_t len | The number of bytes received. |
Remarks
Because the number of bytes to recveive will be unkown if the data to receive is chunk encoded, a WebserverPostRecvResult() callback
will be called with buffer nullptr and len 0. This remarks the end of the transfer. It also works for streamed data transfer. So it isn't
necessary to count the number of bytes received (except the application has futher usage for that informations like realizing a progressbar).
WebserverPostRecvBuffer
If IWebserverPost::Recv() will be called with buffer = nullptr, the IWebserverPost handler will call this function to request a buffer to store
the data.
Parameters
| size_t len | The numbert of bytes to transfer. The returned buffer must provide at least that size. |
Return value
The buffer to store the data to. Must not be nullptr.
WebserverPostCloseComplete
Will be called after the connection had been called. This can be a result of calling IWebserverPost::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverPost instance.
Parameters
| IWebserverPost * const webserverPost | The calling IWebserverPost instance. |
IWebserverPut
class IWebserverPut {
public:
virtual ~IWebserverPut() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual ulong64 GetDataSize();
virtual bool DataIsChunkEncoded();
virtual const char * GetHeaderFieldValue(const char * fieldName);
virtual void SetResultCode(ws_webdav_result_t result, ulong64 dataSize = 0);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void Send(void * buffer, size_t len);
virtual void Recv(void * buffer = nullptr, size_t len = 0);
virtual void Close();
};
Overview
This handler is for handling PUT requests.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetDataSize
Return value
The number of bytes sent with the PUT request. The data can be received by calling IWebserverPut::Recv(). If the data is chunke encoded, the size is unkown and 0 will be returned.
DataIsChunkEncoded
Return value
True if the data to receive is chunk encoded, else false.
GetHeaderFieldValue
Returns the value of the given header filed sent with the request.
Parameters
| const char * fieldName | The name of the header field. |
Return value
The value assigned to the header field or nullptr, if the requested header field doesn't exist.
SetResultCode
Set the result code and optionally the data size for the requests answer.
Parameters
| ws_webdav_result_t result | The result code to set. See ws_webdav_result_t for details. |
| ulong64 dataSize | The number of data that will be send. Pass WS_RESPONSE_CHUNKED to enabled chunk enconded transfer. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
Cancel
Cancels the PUT request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverPut::WebserverPutCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverPut instance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client.
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverPut::WebserverPutSendResult() of the user passed to IWebserverPlugin::Accept() will be called.
Remarks
Before calling Send(), SetResultCode() must be called. And, if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetResultCode().
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Recv
Receives data sent with the request.
Parameters
| void * buffer | (Default: nullptr) The buffer to store the data to. Must be big enough to be able to receive len bytes of data. |
| size_t len | (Default: 0) The number of bytes to receive. If buffer is not nullptr, len must be > 0. |
Return value
Callbacks
After the data had been read, UWebserverPut::WebserverPutRecvResult() of the user passed to IWebserverPlugin::Accept() will be called. If all data had been read, the WebserverPutRecvResult() will be called with nullptr as buffer and 0 as len.
If buffer is nullptr, UWebserverPut::WebserverPutRecvBuffer() will be called to request the buffer to store the data to.
Remarks
If the data to read is chunk encoded, Recv() should be called (recommended without passing a buffer), until RecvResult() will called with nullptr as buffer and 0 as len. However, this also works for non chunk encoded transfer.
The maximum data to read per Recv() call is WS_MAX_DATA_SIZE.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverPut::WebserverPutCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverPut intance,
because it will no longer be used.
UWebserverPut
class UWebserverPut {
public:
virtual ~UWebserverPut() {}
virtual void WebserverPutRequestAcceptComplete(IWebserverPut * const webserverPut);
virtual void WebserverPutSendResult(IWebserverPut * const webserverPut);
virtual void WebserverPutRecvResult(IWebserverPut * const webserverPut, void * buffer, size_t len);
virtual void * WebserverPutRecvBuffer(size_t len) { return nullptr; }
virtual void WebserverPutCloseComplete(IWebserverPut * const webserverPut);
};
Overview
This is the user for a PUT request handler. The application needs to implement the functions below. The UWebserverPut instance must be
used to read the data send with the request, if needed.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverPut for more details.
Note that the application is responsible for releasing the UWebserverPut instance!
Public functions
WebserverPutRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming PUT request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverPut instance for later use.
Parameters
| IWebserverPut * const webserverPut | The calling IWebserverPut instance. |
WebserverPutSendResult
Will be called after a data package send by IWebserverPut::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverPut * const webserverPut | The calling IWebserverPut instance. |
WebserverPutRecvResult
Will be called after receiving data, initiated through IWebserverPut::Recv().
Parameters
| IWebserverPut * const webserverPut | The calling IWebserverPut instance. |
| void * buffer | The buffer holding the received data. Will be the same as passed to
IWebserverPut::Recv() or returned by UWebserverPut::WebserverPutRecvBuffer().
Will be nullptr if there is no more data to receive. |
| size_t len | The number of bytes received. |
Remarks
Because the number of bytes to recveive will be unkown if the data to receive is chunk encoded, a WebserverPutRecvResult() callback
will be called with buffer nullptr and len 0. This remarks the end of the transfer. It also works for streamed data transfer. So it isn't
necessary to count the number of bytes received (except the application has futher usage for that informations like realizing a progressbar).
WebserverPutRecvBuffer
If IWebserverPut::Recv() will be called with buffer = nullptr, the IWebserverPut handler will call this function to request a buffer to store
the data.
Parameters
| size_t len | The numbert of bytes to transfer. The returned buffer must provide at least that size. |
Return value
The buffer to store the data to. Must not be nullptr.
WebserverPutCloseComplete
Will be called after the connection had been closed. This can be a result of calling IWebserverPut::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverPut instance.
Parameters
| IWebserverPut * const webserverPut | The calling IWebserverPut instance. |
IWebserverPropfind
class IWebserverPropfind {
public:
virtual ~IWebserverPropfind() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual ulong64 GetDataSize();
virtual bool DataIsChunkEncoded();
virtual const char * GetHeaderFieldValue(const char * fieldName);
virtual void SetResultCode(ws_webdav_result_t result, ulong64 dataSize = 0);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void Recv(void * buffer = nullptr, size_t len = 0);
virtual void Send(void * buffer, size_t len);
virtual void Close();
};
Overview
This handler is for handling PROPFIND requests.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetDataSize
Return value
The number of bytes sent with the PROPFIND request. The data can be received by calling IWebserverPropfind::Recv(). If the data is chunke encoded, the size is unkown and 0 will be returned.
DataIsChunkEncoded
Return value
True if the data to receive is chunk encoded, else false.
GetHeaderFieldValue
Returns the value of the given header filed sent with the request.
Parameters
| const char * fieldName | The name of the header field. |
Return value
The value assigned to the header field or nullptr, if the requested header field doesn't exist.
SetResultCode
Set the result code and optionally the data size for the requests answer.
Parameters
| ws_webdav_result_t result | The result code to set. See ws_webdav_result_t for details. |
| ulong64 dataSize | The number of data that will be send. Pass WS_RESPONSE_CHUNKED to enabled chunk enconded transfer. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
Cancel
Cancels the PROPFIND request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverPropfind::WebserverPropfindCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverPropfind instance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client.
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverPropfind::WebserverPropfindSendResult() of the user passed to IWebserverPlugin::Accept() will be called.
Remarks
Before calling Send(), SetResultCode() must be called. And, if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetResultCode().
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Recv
Receives data sent with the request.
Parameters
| void * buffer | (Default: nullptr) The buffer to store the data to. Must be big enough to be able to receive len bytes of data. |
| size_t len | (Default: 0) The number of bytes to receive. If buffer is not nullptr, len must be > 0. |
Return value
Callbacks
After the data had been read, UWebserverPropfind::WebserverPropfindRecvResult() of the user passed to IWebserverPlugin::Accept() will be called. If all data had been read, the WebserverPropfindRecvResult() will be called with nullptr as buffer and 0 as len.
If buffer is nullptr, UWebserverPropfind::WebserverPropfindRecvBuffer() will be called to request the buffer to store the data to.
Remarks
If the data to read is chunk encoded, Recv() should be called (recommended without passing a buffer), until RecvResult() will called with nullptr as buffer and 0 as len. However, this also works for non chunk encoded transfer.
The maximum data to read per Recv() call is WS_MAX_DATA_SIZE.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverPropfind::WebserverPropfindCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverPropfind intance,
because it will no longer be used.
UWebserverPropfind
class UWebserverPropfind {
public:
virtual ~UWebserverPropfind() {};
virtual void WebserverPropfindRequestAcceptComplete(IWebserverPropfind * const webserverPropfind);
virtual void WebserverPropfindSendResult(IWebserverPropfind * const webserverPropfind);
virtual void WebserverPropfindRecvResult(IWebserverPropfind * const webserverPropfind, void * buffer, size_t len);
virtual void * WebserverPropfindRecvBuffer(size_t len)
{
return nullptr;
}
virtual void WebserverPropfindCloseComplete(IWebserverPropfind * const webserverPropfind);
};
Overview
This is the user for a PROPFIND request handler. The application needs to implement the functions below. The UWebserverPropfind instance must be
used to read the data send with the request, if needed.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverPropfind for more details.
Note that the application is responsible for releasing the UWebserverPropfind instance!
Public functions
WebserverPropfindRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming PROPFIND request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverPropfind instance for later use.
Parameters
| IWebserverPropfind * const webserverPropfind | The calling IWebserverPropfind instance. |
WebserverPropfindSendResult
Will be called after a data package send by IWebserverPropfind::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverPropfind * const webserverPropfind | The calling IWebserverPropfind instance. |
WebserverPropfindRecvResult
Will be called after receiving data, initiated through IWebserverPropfind::Recv().
Parameters
| IWebserverPropfind * const webserverPropfind | The calling IWebserverPropfind instance. |
| void * buffer | The buffer holding the received data. Will be the same as passed to
IWebserverPropfind::Recv() or returned by UWebserverPropfind::WebserverPropfindRecvBuffer().
Will be nullptr if there is no more data to receive. |
| size_t len | The number of bytes received. |
Remarks
Because the number of bytes to recveive will be unkown if the data to receive is chunk encoded, a WebserverPropfindRecvResult() callback
will be called with buffer nullptr and len 0. This remarks the end of the transfer. It also works for streamed data transfer. So it isn't
necessary to count the number of bytes received (except the application has futher usage for that informations like realizing a progressbar).
WebserverPropfindRecvBuffer
If IWebserverPropfind::Recv() will be called with buffer = nullptr, the IWebserverPropfind handler will call this function to request a buffer to store
the data.
Parameters
| size_t len | The numbert of bytes to transfer. The returned buffer must provide at least that size. |
Return value
The buffer to store the data to. Must not be nullptr.
WebserverPropfindCloseComplete
Will be called after the connection had been closed. This can be a result of calling IWebserverPropfind::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverPropfind instance.
Parameters
| IWebserverPropfind * const webserverPropfind | The calling IWebserverPropfind instance. |
IWebserverMove
class IWebserverMove {
public:
virtual ~IWebserverMove() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual const char * GetHeaderFieldValue(const char * fieldName);
virtual void SetResultCode(ws_webdav_result_t result, ulong64 dataSize = 0);
virtual void SetLocation(const char * location);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void Send(void * buffer, size_t len);
virtual void Close();
};
Overview
This handler is for handling MOVE requests.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetHeaderFieldValue
Returns the value of the given header filed sent with the request.
Parameters
| const char * fieldName | The name of the header field. |
Return value
The value assigned to the header field or nullptr, if the requested header field doesn't exist.
SetResultCode
Set the result code and optionally the data size for the requests answer.
Remarks
Note that SetLocation() must be called before sending data or closing the request.
Parameters
| ws_webdav_result_t result | The result code to set. See ws_webdav_result_t for details. |
| ulong64 dataSize | The number of data that will be send. Pass WS_RESPONSE_CHUNKED to enabled chunk enconded transfer. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
SetLocation
Set the location the data / file had been moved to.
Parameters
| const char * location | The new location of the data / file. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
Cancel
Cancels the MOVE request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverMove::WebserverMoveCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverMove instance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client.
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverMove::WebserverMoveSendResult() of the user passed to IWebserverPlugin::Accept() will be called.
Remarks
Before calling Send(), SetResultCode() must be called. And, if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetResultCode().
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverMove::WebserverMoveCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverMove intance,
because it will no longer be used.
UWebserverMove
class UWebserverMove {
public:
virtual ~UWebserverMove() {};
virtual void WebserverMoveRequestAcceptComplete(IWebserverMove * const webserverMove);
virtual void WebserverMoveSendResult(IWebserverMove * const webserverMove);
virtual void WebserverMoveCloseComplete(IWebserverMove * const webserverMove);
};
Overview
This is the user for a MOVE request handler. The application needs to implement the functions below.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverMove for more details.
Note that the application is responsible for releasing the UWebserverMove instance!
Public functions
WebserverMoveRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming MOVE request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverMove instance for later use.
Parameters
| IWebserverMove * const webserverMove | The calling IWebserverMove instance. |
WebserverMoveSendResult
Will be called after a data package send by IWebserverMove::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverMove * const webserverMove | The calling IWebserverMove instance. |
WebserverMoveCloseComplete
Will be called after the connection had been closed. This can be a result of calling IWebserverMove::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverMove instance.
Parameters
| IWebserverMove * const webserverMove | The calling IWebserverMove instance. |
IWebserverMkCol
class IWebserverMkCol {
public:
virtual ~IWebserverMkCol() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual const char * GetHeaderFieldValue(const char * fieldName);
virtual void SetResultCode(ws_webdav_result_t result, ulong64 dataSize = 0);
virtual void SetLocation(const char * location);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void Send(void * buffer, size_t len);
virtual void Close();
};
Overview
This handler is for handling MKCOL requests.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetHeaderFieldValue
Returns the value of the given header filed sent with the request.
Parameters
| const char * fieldName | The name of the header field. |
Return value
The value assigned to the header field or nullptr, if the requested header field doesn't exist.
SetResultCode
Set the result code and optionally the data size for the requests answer.
Parameters
| ws_webdav_result_t result | The result code to set. See ws_webdav_result_t for details. |
| ulong64 dataSize | The number of data that will be send. Pass WS_RESPONSE_CHUNKED to enabled chunk enconded transfer. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
SetLocation
Set the location the created collection.
Remarks
Note that SetLocation() must be called before sending data or closing the request.
Parameters
| const char * location | The location of the created collection. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
Cancel
Cancels the MKCOL request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverMkCol::WebserverMkColCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverMkCol instance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client.
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverMkCol::WebserverMkColSendResult() of the user passed to IWebserverPlugin::Accept() will be called.
Remarks
Before calling Send(), SetResultCode() must be called. And, if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetResultCode().
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverMkCol::WebserverMkColCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverMkCol intance,
because it will no longer be used.
UWebserverMkCol
class UWebserverMkCol {
public:
virtual ~UWebserverMkCol() {};
virtual void WebserverMkColRequestAcceptComplete(IWebserverMkCol * const webserverMkCol);
virtual void WebserverMkColSendResult(IWebserverMkCol * const webserverMkCol);
virtual void WebserverMkColCloseComplete(IWebserverMkCol * const webserverMkCol);
};
Overview
This is the user for a MKCOL request handler. The application needs to implement the functions below.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverMkCol for more details.
Note that the application is responsible for releasing the UWebserverMkCol instance!
Public functions
WebserverMkColRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming MKCOL request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverMkCol instance for later use.
Parameters
| IWebserverMkCol * const webserverMkCol | The calling IWebserverMkCol instance. |
WebserverMkColSendResult
Will be called after a data package send by IWebserverMkCol::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverMkCol * const webserverMkCol | The calling IWebserverMkCol instance. |
WebserverMkColCloseComplete
Will be called after the connection had been closed. This can be a result of calling IWebserverMkCol::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverMkCol instance.
Parameters
| IWebserverMkCol * const webserverMkCol | The calling IWebserverMkCol instance. |
IWebserverCopy
class IWebserverCopy {
public:
virtual ~IWebserverCopy() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual const char * GetHeaderFieldValue(const char * fieldName);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void SetResultCode(ws_webdav_result_t result, ulong64 dataSize = 0);
virtual void Send(void * buffer, size_t len);
virtual void Close();
};
Overview
This handler is for handling COPY requests.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetHeaderFieldValue
Returns the value of the given header filed sent with the request.
Parameters
| const char * fieldName | The name of the header field. |
Return value
The value assigned to the header field or nullptr, if the requested header field doesn't exist.
SetResultCode
Set the result code and optionally the data size for the requests answer.
Parameters
| ws_webdav_result_t result | The result code to set. See ws_webdav_result_t for details. |
| ulong64 dataSize | The number of data that will be send. Pass WS_RESPONSE_CHUNKED to enabled chunk enconded transfer. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
Cancel
Cancels the COPY request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverCopy::WebserverCopyCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverCopy instance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client.
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverCopy::WebserverCopySendResult() of the user passed to IWebserverPlugin::Accept() will be called.
Remarks
Before calling Send(), SetResultCode() must be called. And, if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetResultCode().
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverCopy::WebserverCopyCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverCopy intance,
because it will no longer be used.
UWebserverCopy
class UWebserverCopy {
public:
virtual ~UWebserverCopy() {};
virtual void WebserverCopyRequestAcceptComplete(IWebserverCopy * const webserverCopy);
virtual void WebserverCopySendResult(IWebserverCopy * const webserverCopy);
virtual void WebserverCopyCloseComplete(IWebserverCopy * const webserverCopy);
};
Overview
This is the user for a COPY request handler. The application needs to implement the functions below.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverCopy for more details.
Note that the application is responsible for releasing the UWebserverCopy instance!
Public functions
WebserverCopyRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming COPY request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverCopy instance for later use.
Parameters
| IWebserverCopy * const webserverCopy | The calling IWebserverCopy instance. |
WebserverCopySendResult
Will be called after a data package send by IWebserverCopy::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverCopy * const webserverCopy | The calling IWebserverCopy instance. |
WebserverCopyCloseComplete
Will be called after the connection had been closed. This can be a result of calling IWebserverCopy::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverCopy instance.
Parameters
| IWebserverCopy * const webserverCopy | The calling IWebserverCopy instance. |
IWebserverDelete
class IWebserverDelete {
public:
virtual ~IWebserverDelete() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual const char * GetHeaderFieldValue(const char * fieldName);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void SetResultCode(ws_webdav_result_t result, ulong64 dataSize = 0);
virtual void Send(void * buffer, size_t len);
virtual void Close();
};
Overview
This handler is for handling DELETE requests.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetHeaderFieldValue
Returns the value of the given header filed sent with the request.
Parameters
| const char * fieldName | The name of the header field. |
Return value
The value assigned to the header field or nullptr, if the requested header field doesn't exist.
SetResultCode
Set the result code and optionally the data size for the requests answer.
Parameters
| ws_webdav_result_t result | The result code to set. See ws_webdav_result_t for details. |
| ulong64 dataSize | The number of data that will be send. Pass WS_RESPONSE_CHUNKED to enabled chunk enconded transfer. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
Cancel
Cancels the DELETE request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverDelete::WebserverDeleteCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverDelete instance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client.
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverDelete::WebserverDeleteSendResult() of the user passed to IWebserverPlugin::Accept() will be called.
Remarks
Before calling Send(), SetResultCode() must be called. And, if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetResultCode().
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverDelete::WebserverDeleteCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverDelete intance,
because it will no longer be used.
UWebserverDelete
class UWebserverDelete {
public:
virtual ~UWebserverDelete() {};
virtual void WebserverDeleteRequestAcceptComplete(IWebserverDelete * const webserverDelete);
virtual void WebserverDeleteSendResult(IWebserverDelete * const webserverDelete);
virtual void WebserverDeleteCloseComplete(IWebserverDelete * const webserverDelete);
};
Overview
This is the user for a DELETE request handler. The application needs to implement the functions below.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverDelete for more details.
Note that the application is responsible for releasing the UWebserverDelete instance!
Public functions
WebserverDeleteRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming DELETE request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverDelete instance for later use.
Parameters
| IWebserverDelete * const webserverDelete | The calling IWebserverDelete instance. |
WebserverDeleteSendResult
Will be called after a data package send by IWebserverDelete::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverDelete * const webserverDelete | The calling IWebserverDelete instance. |
WebserverDeleteCloseComplete
Will be called after the connection had been closed. This can be a result of calling IWebserverDelete::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverDelete instance.
Parameters
| IWebserverDelete * const webserverDelete | The calling IWebserverDelete instance. |
IWebserverLock
class IWebserverLock {
public:
virtual ~IWebserverLock() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual const char * GetHeaderFieldValue(const char * fieldName);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void SetResultCode(ws_webdav_result_t result, size_t dataSize = 0);
virtual void Recv(void * buffer = nullptr, size_t len = 0);
virtual void Send(void * buffer, size_t len);
virtual void Close();
};
Overview
This handler is for handling LOCK requests.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetHeaderFieldValue
Returns the value of the given header filed sent with the request.
Parameters
| const char * fieldName | The name of the header field. |
Return value
The value assigned to the header field or nullptr, if the requested header field doesn't exist.
SetResultCode
Set the result code and optionally the data size for the requests answer.
Parameters
| ws_webdav_result_t result | The result code to set. See ws_webdav_result_t for details. |
| ulong64 dataSize | The number of data that will be send. Pass WS_RESPONSE_CHUNKED to enabled chunk enconded transfer. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
Cancel
Cancels the LOCK request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverLock::WebserverLockCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverLock instance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client.
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverLock::WebserverLockSendResult() of the user passed to IWebserverPlugin::Accept() will be called.
Remarks
Before calling Send(), SetResultCode() must be called. And, if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetResultCode().
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Recv
Receives data sent with the request.
Parameters
| void * buffer | (Default: nullptr) The buffer to store the data to. Must be big enough to be able to receive len bytes of data. |
| size_t len | (Default: 0) The number of bytes to receive. If buffer is not nullptr, len must be > 0. |
Return value
Callbacks
After the data had been read, UWebserverLock::WebserverLockRecvResult() of the user passed to IWebserverPlugin::Accept() will be called. If all data had been read, the WebserverLockRecvResult() will be called with nullptr as buffer and 0 as len.
If buffer is nullptr, UWebserverLock::WebserverLockRecvBuffer() will be called to request the buffer to store the data to.
Remarks
If the data to read is chunk encoded, Recv() should be called (recommended without passing a buffer), until RecvResult() will called with nullptr as buffer and 0 as len. However, this also works for non chunk encoded transfer.
The maximum data to read per Recv() call is WS_MAX_DATA_SIZE.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverLock::WebserverLockCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverLock intance,
because it will no longer be used.
UWebserverLock
class UWebserverLock {
public:
virtual ~UWebserverLock() {};
virtual void WebserverLockRequestAcceptComplete(IWebserverLock * const webserverLock);
virtual void WebserverLockSendResult(IWebserverLock * const webserverLock);
virtual void WebserverLockRecvResult(IWebserverLock * const webserverLock, void * buffer, size_t len);
virtual void * WebserverLockRecvBuffer(size_t len)
{
return nullptr;
}
virtual void WebserverLockCloseComplete(IWebserverLock * const webserverLock);
};
Overview
This is the user for a LOCK request handler. The application needs to implement the functions below. The UWebserverLock instance must be
used to read the data send with the request, if needed.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverLock for more details.
Note that the application is responsible for releasing the UWebserverLock instance!
Public functions
WebserverLockRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming LOCK request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverLock instance for later use.
Parameters
| IWebserverLock * const webserverLock | The calling IWebserverLock instance. |
WebserverLockSendResult
Will be called after a data package send by IWebserverLock::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverLock * const webserverLock | The calling IWebserverLock instance. |
WebserverLockRecvResult
Will be called after receiving data, initiated through IWebserverLock::Recv().
Parameters
| IWebserverLock * const webserverLock | The calling IWebserverLock instance. |
| void * buffer | The buffer holding the received data. Will be the same as passed to
IWebserverLock::Recv() or returned by UWebserverLock::WebserverLockRecvBuffer().
Will be nullptr if there is no more data to receive. |
| size_t len | The number of bytes received. |
Remarks
Because the number of bytes to recveive will be unkown if the data to receive is chunk encoded, a WebserverLockRecvResult() callback
will be called with buffer nullptr and len 0. This remarks the end of the transfer. It also works for streamed data transfer. So it isn't
necessary to count the number of bytes received (except the application has futher usage for that informations like realizing a progressbar).
WebserverLockRecvBuffer
If IWebserverLock::Recv() will be called with buffer = nullptr, the IWebserverLock handler will call this function to request a buffer to store
the data.
Parameters
| size_t len | The numbert of bytes to transfer. The returned buffer must provide at least that size. |
Return value
The buffer to store the data to. Must not be nullptr.
WebserverLockCloseComplete
Will be called after the connection had been closed. This can be a result of calling IWebserverLock::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverLock instance.
Parameters
| IWebserverLock * const webserverLock | The calling IWebserverLock instance. |
IWebserverUnlock
class IWebserverUnlock {
public:
virtual ~IWebserverUnlock() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual const char * GetHeaderFieldValue(const char * fieldName);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void SetResultCode(ws_webdav_result_t result, ulong64 dataSize = 0);
virtual void Send(void * buffer, size_t len);
virtual void Close();
};
Overview
This handler is for handling UNLOCK requests.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetHeaderFieldValue
Returns the value of the given header filed sent with the request.
Parameters
| const char * fieldName | The name of the header field. |
Return value
The value assigned to the header field or nullptr, if the requested header field doesn't exist.
SetResultCode
Set the result code and optionally the data size for the requests answer.
Parameters
| ws_webdav_result_t result | The result code to set. See ws_webdav_result_t for details. |
| ulong64 dataSize | The number of data that will be send. Pass WS_RESPONSE_CHUNKED to enabled chunk enconded transfer. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
Cancel
Cancels the UNLOCK request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverUnlock::WebserverUnlockCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverUnlock instance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client.
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverUnlock::WebserverUnlockSendResult() of the user passed to IWebserverPlugin::Accept() will be called.
Remarks
Before calling Send(), SetResultCode() must be called. And, if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetResultCode().
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverUnlock::WebserverUnlockCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverUnlock intance,
because it will no longer be used.
UWebserverUnlock
class UWebserverUnlock {
public:
virtual ~UWebserverUnlock() {};
virtual void WebserverUnlockRequestAcceptComplete(IWebserverUnlock * const webserverUnlock);
virtual void WebserverUnlockSendResult(IWebserverUnlock * const webserverUnlock);
virtual void WebserverUnlockCloseComplete(IWebserverUnlock * const webserverUnlock);
};
Overview
This is the user for a UNLOCK request handler. The application needs to implement the functions below.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverUnlock for more details.
Note that the application is responsible for releasing the UWebserverUnlock instance!
Public functions
WebserverUnlockRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming UNLOCK request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverUnlock instance for later use.
Parameters
| IWebserverUnlock * const webserverUnlock | The calling IWebserverUnlock instance. |
WebserverUnlockSendResult
Will be called after a data package send by IWebserverUnlock::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverUnlock * const webserverUnlock | The calling IWebserverUnlock instance. |
WebserverUnlockCloseComplete
Will be called after the connection had been closed. This can be a result of calling IWebserverUnlock::Close() or because of a close
initiated by the client. This function is the right place to clean up and release the UWebserverUnlock instance.
Parameters
| IWebserverUnlock * const webserverUnlock | The calling IWebserverUnlock instance. |
IWebserverProppatch
class IWebserverProppatch {
public:
virtual ~IWebserverProppatch() {}
virtual const char * GetResourceName();
virtual const char * GetRegisteredPathForRequest();
virtual const char * GetHeaderFieldValue(const char * fieldName);
virtual void Cancel(wsr_cancel_type_t reason);
virtual void SetResultCode(ws_webdav_result_t result, ulong64 dataSize = 0);
virtual void Recv(void * buffer = nullptr, size_t len = 0);
virtual void Send(void * buffer, size_t len);
virtual void Close();
};
Overview
This handler is for handling PROPPATCH requests.
Public functions
GetResourceName
Return value
The name of the resource for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as resourceName.
GetRegisteredPathForRequest
Return value
The name of the registered path for that request. The value returned is the same as passed to UWebserverPlugin::WebserverPluginHttpListenResult() as registeredPathForRequest.
GetHeaderFieldValue
Returns the value of the given header filed sent with the request.
Parameters
| const char * fieldName | The name of the header field. |
Return value
The value assigned to the header field or nullptr, if the requested header field doesn't exist.
SetResultCode
Set the result code and optionally the data size for the requests answer.
Parameters
| ws_webdav_result_t result | The result code to set. See ws_webdav_result_t for details. |
| ulong64 dataSize | The number of data that will be send. Pass WS_RESPONSE_CHUNKED to enabled chunk enconded transfer. |
Remarks
SetResultCode() must be called before sending data or, in case that no data will be send, before closing the request.
The application must send the exact number of bytes using Send(), as given to SetTransferInfo(). If not, the HTTP client may be waiting for ever or ending up in an HTTP parsing error.
In chunk encoded mode, the application simply can send data as long as needed. When calling Close(), the chunk encoded transfer will be finalized.
Cancel
Cancels the PROPPATCH request. If the application already started to send data, the transfare will be canceled. If not, calling Cancel() will be the same as calling IWebserverPlugin::Cancel() when receiveing the request.
Parameters
| wsr_cancel_type_t reason | The reason for canceling the request. See wsr_cancel_type_t for more details. |
Callbacks
Because Cancel() also closes the transfer, UWebserverProppatch::WebserverProppatchCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverProppatch instance,
because it will no longer be used.
Remarks
Cancel will automatically close the request. So there is no need to call close, too.
The reason only will be of interest if the application not already started to send a response. If already started, the reason will be ignored.
Send
Sends the give data to the client.
Parameters
| void * buffer | The pointer to the buffer with the data to send. Must hold at least len byte of data. |
| size_t len | The number bytes to send. |
Callbacks
After the data had been sent, UWebserverProppatch::WebserverProppatchSendResult() of the user passed to IWebserverPlugin::Accept() will be called.
Remarks
Before calling Send(), SetResultCode() must be called. And, if not called to enabled chunk encoded transfer, the application had to send the number of bytes as given to SetResultCode().
The number of bytes to send must not exceed WS_MAX_DATA_SIZE, or an assertion will be thrown. If more than WS_MAX_DATA_SIZE need to be send, the application must call Send() multiple times.
Recv
Receives data sent with the request.
Parameters
| void * buffer | (Default: nullptr) The buffer to store the data to. Must be big enough to be able to receive len bytes of data. |
| size_t len | (Default: 0) The number of bytes to receive. If buffer is not nullptr, len must be > 0. |
Return value
Callbacks
After the data had been read, UWebserverProppatch::WebserverProppatchRecvResult() of the user passed to IWebserverPlugin::Accept() will be called. If all data had been read, the WebserverProppatchRecvResult() will be called with nullptr as buffer and 0 as len.
If buffer is nullptr, UWebserverProppatch::WebserverProppatchRecvBuffer() will be called to request the buffer to store the data to.
Remarks
If the data to read is chunk encoded, Recv() should be called (recommended without passing a buffer), until RecvResult() will called with nullptr as buffer and 0 as len. However, this also works for non chunk encoded transfer.
The maximum data to read per Recv() call is WS_MAX_DATA_SIZE.
Close
Closes the request. This also finalizes a chunk encoded response, so that the client will receive the information that all data had been transfered.
Callbacks
After the connection had been closed, UWebserverProppatch::WebserverProppatchCloseComplete() of the user passed to IWebserverPlugin::Accept() will be called. This is the right place to delete the IWebserverProppatch intance,
because it will no longer be used.
UWebserverProppatch
class UWebserverProppatch {
public:
virtual ~UWebserverProppatch() {};
virtual void WebserverProppatchRequestAcceptComplete(IWebserverProppatch * const webserverProppatch);
virtual void WebserverProppatchSendResult(IWebserverProppatch * const webserverProppatch);
virtual void WebserverProppatchRecvResult(IWebserverProppatch * const webserverProppatch, void * buffer, size_t len);
virtual void * WebserverProppatchRecvBuffer(size_t len)
{
return nullptr;
}
virtual void WebserverProppatchCloseComplete(IWebserverProppatch * const webserverProppatch);
};
Overview
This is the user for a PROPPATCH request handler. The application needs to implement the functions below. The UWebserverProppatch instance must be
used to read the data send with the request, if needed.
Remarks
If sending a response, it can (and should) be done asynchronously. But the application must take care sending the same number of bytes as defined before
start sending data (if using streamed transfer) and closing the connection. Also the correct datatype and transfer info must be set before. If not, the
browser (our whatever client) will wait for incomming data or at least recognize a transfer error.
See IWebserverProppatch for more details.
Note that the application is responsible for releasing the UWebserverProppatch instance!
Public functions
WebserverProppatchRequestAcceptComplete
Will be called from the IWebserverPlugin Instance after the application accepts an incoming PROPPATCH request. This will be the correct
place to start answering the request. A derived class need to save the pointer of the given IWebserverProppatch instance for later use.
Parameters
| IWebserverProppatch * const webserverProppatch | The calling IWebserverProppatch instance. |
WebserverProppatchSendResult
Will be called after a data package send by IWebserverProppatch::Send() had been send to the client by the webserver itself.
Parameters
| IWebserverProppatch * const webserverProppatch | The calling IWebserverProppatch instance. |
WebserverProppatchRecvResult
Will be called after receiving data, initiated through IWebserverProppatch::Recv().
Parameters
| IWebserverProppatch * const webserverProppatch | The calling IWebserverProppatch instance. |
| void * buffer | The buffer holding the received data. Will be the same as passed to
IWebserverProppatch::Recv() or returned by UWebserverProppatch::WebserverProppatchRecvBuffer().
Will be nullptr if there is no more data to receive. |
| size_t len | The number of bytes received. |
Remarks
Because the number of bytes to recveive will be unkown if the data to receive is chunk encoded, a WebserverProppatchRecvResult() callback
will be called with buffer nullptr and len 0. This remarks the end of the transfer. It also works for streamed data transfer. So it isn't
necessary to count the number of bytes received (except the application has futher usage for that informations like realizing a progressbar).
WebserverProppatchRecvBuffer
If IWebserverProppatch::Recv() will be called with buffer = nullptr, the IWebserverProppatch handler will call this function to request a buffer to store
the data.
Parameters
| size_t len | The numbert of bytes to transfer. The returned buffer must provide at least that size. |
Return value
The buffer to store the data to. Must not be nullptr.
WebserverProppatchCloseComplete