cgi.h - Nandakumar CGI Library (libnancgi) Documentation

void
nan_getrandom_alnum ( char *buf,
                      size_t buflen,
                      unsigned int flags )

This function in for internal use only.

Get a random string with alphanumeric characters.

static inline const NanKVPNode*
nan_kvp_find ( const NanKVPNode *node,
               const char *key )

This function in for internal use only.

Scans through the list starting from 'node', and returns the first node with a matching key.

static inline NanKVPNode*
nan_kvp_node_append ( NanKVPNode *node,
                      const char *key,
                      const char *value )

This function in for internal use only.

warning - Pointers key and value are directly assigned without duplicating the content.

static inline NanKVPNode*
nan_kvp_tail_append ( NanKVPNode **tail,
                      const char *key,
                      const char *value )

This function in for internal use only.

Appends a node and updates the tail.

returns - The newly appended node on success, NULL on failure (keeps tail intact on failure).

warning - Pointers key and value are directly assigned without duplicating the content.

static inline void
ncgi_begin_html (  )

A convenience function to close the HTTP header after specifying the Content-Type to be "text/html", so that one could readily start produce visible output using functions like printf().

char*
ncgi_cookie_get ( const char *name )

returns - A newly-allocated string containing the cookie value on success, NULL on failure. Caller should free this after use.

static inline void
ncgi_cookie_set ( const char *name,
                  const char *value )

Sets a cookie. This function should be called before the header is closed. Internally, the function simply prints a "Set-Cookie: NAME=VALUE" line. This means you can append the value with valid flags and parameters like HttpOnly. For example, one could call:

 ncgi_cookie_set("uname", "user1; HttpOnly; Secure; SameSite=Strict");

int
ncgi_echo_file ( const char *fname )

Prints the contents of a file. For a practical example, one could use three calls to this function to serve pages with a common header and footer, but exclusive body:

 ncgi_echo_file("../src/header.html");
 ncgi_echo_file(page_body_path);
 ncgi_echo_file("../src/footer.html");

returns - 0 on success, -1 on failure.

static inline void
ncgi_header_init ( char *content_type )

A convenience function to start the HTTP header by specifying a content type. If used, it must be called before the header is closed.

static inline void
ncgi_header_close (  )

Closes the HTTP header by printing " ". One can do this by hand, however, this function makes the code look more clean.

note - You must close the header before any actual output is made. You can also use the function ncgi_begin_html(), which will automatically set the content type and close the header.

static inline const char*
ncgi_post_get_field ( const char *key )

Returns the value of a field from the POST data.

returns - value of the field if found, NULL if not.

warning - Supports urlencoded POST requests only; multipart won't work. See ncgi_post_parse() for more details.

int
ncgi_post_parse (  )

This function in for internal use only.

Parses the POST data and fills the list pointed by ncgi_postlist_head.

returns - 0 on success, -1 on failure.

warning - (1) This function should only be called once. (2) It only handles urlencoded POST requests; multipart is not supported.

static inline const char*
ncgi_query_get_field ( const char *key )

Returns the value of a field from the query string (i.e., GET request).

returns - value of the field if found, NULL if not. Various cases are illustrated below for ncgi_query_get_field("month"):

 http://example.com/index.cgi?year=2018&month=06&day=17
   => "06"
 http://example.com/index.cgi
   => NULL
 http://example.com/index.cgi?
   => NULL
 http://example.com/index.cgi?month
   => ""
 http://example.com/index.cgi?month=
   => "" (empty string)
 http://example.com/index.cgi?month=&year=2018
   => ""

note - Query String is the part followed by the question mark, not the entire URL.

static inline int
ncgi_query_parse (  )

This function in for internal use only.

Parses the Query String and fills the list pointed by ncgi_querylist_head.

returns - 0 on success, -1 on failure.

warning - This function should only be called once.

int
ncgi_request_parse ( const char *reqstr,
                     NanKVPNode **kvplist_tail,
                     bool *flag_parsed )

This function in for internal use only.

Parse a URL-encoded request string. This is the function that works behind ncgi_query_parse() and ncgi_post_parse()

returns - 0 on success, -1 on failure.

warning - This function should only be called once.

int
ncgi_session_create (  )

Creates and starts a session.

warning - Call before closing the HTTP header.

static inline char*
ncgi_session_get_datafile_path (  )

This function in for internal use only.

Gets the path to the file where ncgi stores the current session's data.

returns - a file path.

static inline char*
ncgi_session_get_id (  )

This function in for internal use only.

Gets the Session ID. This is the value set by a Session Cookie.

returns - an alphanumeric string of fixed length.

static inline char*
ncgi_session_get_property_str ( const char *name )

Gets a Session Property String, which was once set by the caller. This is similar to reading the value of a member of the array $_SESSION in PHP. See ncgi_session_set_property_str() for more details.

warning - Use this function only to retrieve information stored using ncgi_session_set_property_str(). This function is not binary-friendly and doesn't automatically convert binary session properties to text.

returns - value of a Session Property String (null-terminated). TODO how to get bin data?

char*
ncgi_session_get_valid_id_from_cookie (  )

This function in for internal use only.

Gets and validates the Session ID string from Cookie in HTTP Request.

warning - The returned string must be freed by the caller.

int
ncgi_session_read_data (  )

This function in for internal use only.

void
ncgi_session_reset_data (  )

warning - This function clears in-memory data only. Call ncgi_session_write_data() for persistence.

int
ncgi_session_resume (  )

Sets the variables and loads the data to continue an on-going session identified using the Session ID cookie.

returns - 0 if the session exists and it was loaded, -1 otherwise.

int
ncgi_session_resume_without_data (  )

Similar to ncgi_session_resume(), except that this function avoids loading the session data (except the Session ID) for fast execution.

returns - 0 if the session exists and it was loaded, -1 otherwise.

int
ncgi_session_set_property_str ( const char *name,
                                const char *value )

Sets a Session Property String. This is similar to setting the value of a member of the array $_SESSION in PHP. One usually stores information related to a session as Session Properties in ncgi. For instance, if you accepted a user login and want to set his uname as part of the session data, this is the function you should use.

warning - (1) Call ncgi_session_write_data() to save the session data to the disk. Otherwise you won't be able to retrieve the newly set information from another file, while processing the next request from the same user. (2) Use this function only to set null-terminated strings. This function is not binary-friendly and doesn't automatically convert binary blocks to text. TODO how to do that

returns - 0 on success, -1 on failure.

int
ncgi_session_write_data (  )

warning - This function calculates the lengths of the null-terminated strings and stores in the list itself. Shouldn't cause any issue if you don't use NanSessionProperty.len for any other purpose.

int
ncgi_urldecode ( const char *src,
                 char *dest )

Decodes a URL-encoded string. For example, if src is "100%25%20Sure!", then dest will be filled with "100% Sure!".

bool
ncgi_validate_session_id ( const char *sessid )

Helps prevent injection attacks, especially when session data files are consulted (path injection).

returns - true if sessid is valid, false otherwise