libwebsockets
Lightweight C library for HTML5 websockets
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
dataopt_data pointer set in lws_spa_create
namename of the form field being uploaded
filenameoriginal filename from client
bufstart of data to receive
lenlength of data to receive
stateinformation 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

#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

46  {
55 };
@ LWS_UFS_CLOSE
Definition: lws-spa.h:53
@ LWS_UFS_OPEN
Definition: lws-spa.h:51
@ LWS_UFS_FINAL_CONTENT
Definition: lws-spa.h:49
@ LWS_UFS_CONTENT
Definition: lws-spa.h:47

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
wsilws connection (used to find Content Type)
param_namesarray of form parameter names, like "username"
count_paramscount of param_names
max_storagetotal amount of form parameter values we can store
opt_cbNULL, or callback to receive file upload data.
opt_dataNULL, 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
wsilws connection (used to find Content Type)
infopointer 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
spathe 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
spathe 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
spathe parser object previously created
nparameter 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
spathe parser object previously created
nparameter 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
spathe parser object previously created
inincoming urlencoded data
lencount of bytes valid at in