CoAP file server

Library for serving files from the VFS to CoAP clients. More...

Detailed Description

Library for serving files from the VFS to CoAP clients.

About

This maps files in the local file system onto a resources in CoAP. In that, it is what is called a static web server in the unconstrained web.

As usual, GET operations are used to read files and PUT writes to files. In the current implementation, PUTs are expressed as random-access, meaning that files are not updated atomically, although files are created atomically. The Content-Format option is not checked in the current implementation. Conditional file modification and deletion is supported using the If-Match option. The If-Match option carries a previously received Etag or in case of zero length, requires a request to be processed only if the resource exists. In opposite, the If-None-Match option requires a request to be processed, only if the resource does not yet exist, and is most useful for file creation.

Directories are expressed to URIs with trailing slashes. Directories and their content are deleted as if one would do an $rm -r. If you only would like to delete a directory if it is empty, you must supply an If-Match option with the special value COAPFILESERVER_DIR_DELETE_ETAG.

Note

The file server uses ETag for cache validation. The ETags are built from the file system stat values. As clients rely on the ETag to differ when the file changes, it is important that file modification times are set. The precise time values do not matter, but if a file is changed in place and neither its length nor its modification time is varied, then clients will not become aware of the change or may even mix up the versions half way through if they have a part of the old version cached.

Usage

• USEMODULE += nanocoap_fileserver

• Enter a nanocoap_fileserver_handler handler into your CoAP server's resource list like this:

  static const coap_resource_t _resources[] = {
      ...
      {
         .path = "/files/sd",
         .methods = COAP_GET | COAP_MATCH_SUBTREE,
         .handler = nanocoap_fileserver_handler,
         .context = "/sd0"
      },
      ...
  }

  The path argument specifies under which path the folder is served via CoAP while the context argument contains the path on the local filesystem that will be served.

  The allowed methods dictate whether it's read-only (COAP_GET) or read-write (COAP_GET | COAP_PUT | COAP_DELETE). If you want to support PUT and DELETE, you need to enable the modules nanocoap_fileserver_put and nanocoap_fileserver_delete.

Files
file	fileserver.h
	Resource handler for the CoAP file system server.

Data Structures
struct	nanocoap_fileserver_event_ctx_t
	GCoAP fileserver event context. More...

Macros
#define	COAPFILESERVER_DIR_DELETE_ETAG   (0x6ce88b56u)
	Randomly generated Etag, used by a client when a directory should only be deleted, if it is empty.

Typedefs
typedef void(*	nanocoap_fileserver_event_handler_t) (nanocoap_fileserver_event_t event, nanocoap_fileserver_event_ctx_t *ctx)
	GCoAP fileserver event callback type.

Enumerations
enum	nanocoap_fileserver_event_t {   NANOCOAP_FILESERVER_GET_FILE_START , NANOCOAP_FILESERVER_GET_FILE_END , NANOCOAP_FILESERVER_PUT_FILE_START , NANOCOAP_FILESERVER_PUT_FILE_END ,   NANOCOAP_FILESERVER_DELETE_FILE }
	GCoAP fileserver event types. More...

Functions
void	nanocoap_fileserver_set_event_cb (nanocoap_fileserver_event_handler_t cb, void *arg)
	Register a consumer for GCoAP fileserver events Requires the nanocoap_fileserver_callback module.
ssize_t	nanocoap_fileserver_handler (coap_pkt_t *pdu, uint8_t *buf, size_t len, coap_request_ctx_t *ctx)
	File server handler.

Macro Definition Documentation

COAPFILESERVER_DIR_DELETE_ETAG

#define COAPFILESERVER_DIR_DELETE_ETAG   (0x6ce88b56u)

Randomly generated Etag, used by a client when a directory should only be deleted, if it is empty.

Definition at line 91 of file fileserver.h.

Typedef Documentation

nanocoap_fileserver_event_handler_t

typedef void(* nanocoap_fileserver_event_handler_t) (nanocoap_fileserver_event_t event, nanocoap_fileserver_event_ctx_t *ctx)

GCoAP fileserver event callback type.

Parameters

[in]	event	Type of the event
[in]	ctx	Event context information

Definition at line 122 of file fileserver.h.

Enumeration Type Documentation

nanocoap_fileserver_event_t

enum nanocoap_fileserver_event_t

GCoAP fileserver event types.

Note

This requires the nanocoap_fileserver_callback module.

Enumerator
NANOCOAP_FILESERVER_GET_FILE_START	file download started
NANOCOAP_FILESERVER_GET_FILE_END	file download finished
NANOCOAP_FILESERVER_PUT_FILE_START	file upload started
NANOCOAP_FILESERVER_PUT_FILE_END	file upload finished
NANOCOAP_FILESERVER_DELETE_FILE	file deletion requested (called before file is deleted)

Definition at line 98 of file fileserver.h.

Function Documentation

nanocoap_fileserver_handler()

ssize_t nanocoap_fileserver_handler	(	coap_pkt_t *	pdu,
		uint8_t *	buf,
		size_t	len,
		coap_request_ctx_t *	ctx
	)

File server handler.

Serve a directory from the VFS as a CoAP resource tree.

See also

CoAP file server

Parameters

[in]	pdu	CoAP request package
[out]	buf	Buffer for the response
[in]	len	Response buffer length
[in]	ctx	pointer to a coap_request_ctx_t

Returns

size of the response on success negative error

nanocoap_fileserver_set_event_cb()

void nanocoap_fileserver_set_event_cb	(	nanocoap_fileserver_event_handler_t	cb,
		void *	arg
	)

Register a consumer for GCoAP fileserver events Requires the nanocoap_fileserver_callback module.

The Callback is called on each fileserver event and executed within the GCoAP thread.

Parameters

[in]	cb	The callback function to be called on events
[in]	arg	Custom callback function context