cgiwritestate() - save state variables to cookie or file

SYNOPSIS

#include "cgi.h"

int  cgiwritestate(cp, tofile)
CGI  *cp;
int  tofile;

DESCRIPTION
The cgiwritestate() function saves the current invocation's state variables (set by putcgi()) by generating an encrypted cookie containing them. The cookie will be returned by the client's Web browser on future invocations, enabling the API to retrieve the state variables from it. A Set-Cookie header is printed to set the cookie.

If tofile is non-zero, the state variables are instead saved to a local file, and the cookie becomes a handle to them. This is useful if the number and size of state variables is expected to be large, greater than about 4k, though it does incur some file I/O (usually 1 read & 1 write).

As it prints an HTTP header, cgiwritestate() must be called between cgistarthdrs() and cgiendhdrs(), yet after all putcgi() calls. It returns 1 if ok, 0 on error, or -1 if the invoking Web browser isn't recognized as one that supports cookies: in this case cgigetstate() must be used to send the state cookie in the URL or a form variable.

CAVEATS
A CGI program must always keep the same value for the tofile flag, either non-zero or zero. If it is changed from one invocation to the next the state variables may be lost. cgiwritestate() may return an error if it is not called during headers (between cgistarthdrs() / cgiendhdrs()), or if called more than once during an invocation.

SEE ALSO
putcgi() cgistarthdrs() cgiendhdrs() cgigetstate()