Form Parsing

Data Structures
struct	lws_spa_create_info

Typedefs
typedef int(*	lws_spa_fileupload_cb) (void *data, const char *name, const char *filename, char *buf, int len, enum lws_spa_fileupload_states state)
typedef struct lws_spa_create_info	lws_spa_create_info_t

Enumerations
enum	lws_spa_fileupload_states { LWS_UFS_CONTENT , LWS_UFS_FINAL_CONTENT , LWS_UFS_OPEN , LWS_UFS_CLOSE }

Functions
LWS_VISIBLE LWS_EXTERN struct lws_spa *	lws_spa_create (struct lws *wsi, const char *const *param_names, int count_params, int max_storage, lws_spa_fileupload_cb opt_cb, void *opt_data)
LWS_VISIBLE LWS_EXTERN struct lws_spa *	lws_spa_create_via_info (struct lws *wsi, const lws_spa_create_info_t *info)
LWS_VISIBLE LWS_EXTERN int	lws_spa_process (struct lws_spa *spa, const char *in, int len)
LWS_VISIBLE LWS_EXTERN int	lws_spa_finalize (struct lws_spa *spa)
LWS_VISIBLE LWS_EXTERN int	lws_spa_get_length (struct lws_spa *spa, int n)
LWS_VISIBLE LWS_EXTERN const char *	lws_spa_get_string (struct lws_spa *spa, int n)
LWS_VISIBLE LWS_EXTERN int	lws_spa_destroy (struct lws_spa *spa)

Detailed Description

POSTed form parsing functions

These lws_spa (stateful post arguments) apis let you parse and urldecode POSTed form arguments, both using simple urlencoded and multipart transfer encoding.

It's capable of handling file uploads as well a named input parsing, and the apis are the same for both form upload styles.

You feed it a list of parameter names and it creates pointers to the urldecoded arguments: file upload parameters pass the file data in chunks to a user-supplied callback as they come.

Since it's stateful, it handles the incoming data needing more than one POST_BODY callback and has no limit on uploaded file size.

Typedef Documentation

lws_spa_fileupload_cb

typedef int(* lws_spa_fileupload_cb) (void *data, const char *name, const char *filename, char *buf, int len, enum lws_spa_fileupload_states state)

#include <include/libwebsockets/lws-spa.h>

lws_spa_fileupload_cb() - callback to receive file upload data

Parameters

data	opt_data pointer set in lws_spa_create
name	name of the form field being uploaded
filename	original filename from client
buf	start of data to receive
len	length of data to receive
state	information about how this call relates to file

Notice name and filename shouldn't be trusted, as they are passed from HTTP provided by the client.

Enumeration Type Documentation

lws_spa_fileupload_states

enum lws_spa_fileupload_states

#include <include/libwebsockets/lws-spa.h>

enum lws_spa_fileupload_states

Enumerator
LWS_UFS_CONTENT	a chunk of file content has arrived
LWS_UFS_FINAL_CONTENT	the last chunk (possibly zero length) of file content has arrived
LWS_UFS_OPEN	a new file is starting to arrive
LWS_UFS_CLOSE	the file decode stuff is being destroyed

                               {
        LWS_UFS_CONTENT,
        LWS_UFS_FINAL_CONTENT,
        LWS_UFS_OPEN,
        LWS_UFS_CLOSE
};

Function Documentation

lws_spa_create()

LWS_VISIBLE LWS_EXTERN struct lws_spa* lws_spa_create	(	struct lws *	wsi,
		const char *const *	param_names,
		int	count_params,
		int	max_storage,
		lws_spa_fileupload_cb	opt_cb,
		void *	opt_data
	)

#include <include/libwebsockets/lws-spa.h>

lws_spa_create() - create urldecode parser

Parameters

wsi	lws connection (used to find Content Type)
param_names	array of form parameter names, like "username"
count_params	count of param_names
max_storage	total amount of form parameter values we can store
opt_cb	NULL, or callback to receive file upload data.
opt_data	NULL, or user pointer provided to opt_cb.

Creates a urldecode parser and initializes it.

It's recommended to use the newer api, lws_spa_create_via_info() instead.

opt_cb can be NULL if you just want normal name=value parsing, however if one or more entries in your form are bulk data (file transfer), you can provide this callback and filter on the name callback parameter to treat that urldecoded data separately. The callback should return -1 in case of fatal error, and 0 if OK.

lws_spa_create_via_info()

LWS_VISIBLE LWS_EXTERN struct lws_spa* lws_spa_create_via_info	(	struct lws *	wsi,
		const lws_spa_create_info_t *	info
	)

#include <include/libwebsockets/lws-spa.h>

lws_spa_create_via_info() - create urldecode parser

Parameters

wsi	lws connection (used to find Content Type)
info	pointer to struct defining the arguments

Creates a urldecode parser and initializes it.

opt_cb can be NULL if you just want normal name=value parsing, however if one or more entries in your form are bulk data (file transfer), you can provide this callback and filter on the name callback parameter to treat that urldecoded data separately. The callback should return -1 in case of fatal error, and 0 if OK.

lws_spa_destroy()

LWS_VISIBLE LWS_EXTERN int lws_spa_destroy

(

struct lws_spa *

spa

)

#include <include/libwebsockets/lws-spa.h>

lws_spa_destroy() - destroy parser object

Parameters

spa	the parser object previously created

lws_spa_finalize()

LWS_VISIBLE LWS_EXTERN int lws_spa_finalize

(

struct lws_spa *

spa

)

#include <include/libwebsockets/lws-spa.h>

lws_spa_finalize() - indicate incoming data completed

Parameters

spa	the parser object previously created

lws_spa_get_length()

LWS_VISIBLE LWS_EXTERN int lws_spa_get_length	(	struct lws_spa *	spa,
		int	n
	)

#include <include/libwebsockets/lws-spa.h>

lws_spa_get_length() - return length of parameter value

Parameters

spa	the parser object previously created
n	parameter ordinal to return length of value for

lws_spa_get_string()

LWS_VISIBLE LWS_EXTERN const char* lws_spa_get_string	(	struct lws_spa *	spa,
		int	n
	)

#include <include/libwebsockets/lws-spa.h>

lws_spa_get_string() - return pointer to parameter value

Parameters

spa	the parser object previously created
n	parameter ordinal to return pointer to value for

lws_spa_process()

LWS_VISIBLE LWS_EXTERN int lws_spa_process	(	struct lws_spa *	spa,
		const char *	in,
		int	len
	)

#include <include/libwebsockets/lws-spa.h>

lws_spa_process() - parses a chunk of input data

Parameters

spa	the parser object previously created
in	incoming urlencoded data
len	count of bytes valid at in