synopsis.
The HyperText Transfer Protocol object, or http_o, is a Z Directory class object that lets you emulate a web browser. It allows you to do GET and POST requests. The class has a myriad of options. However, you may be able to do complete web browser accesses in a few lines of code (see the example, below).

description.
The http object can be reused. In the case of accessing a single web server, if the web server returns a cookie, it will be stored internally in the object when it is recieved. A second access to the same web server will return the cookie value. You can modify or reset cookies prior to doing so.

You have some options to set things in the HTTP request header. Normally the first line of a GET request looks something like this:

GET http://bham.craigslist.org/sof HTTP/1.1

If you want to modify the url part of the line above, you can set it with the member function set_header_url(). Perhaps it should be "/search/sof". If so, call this function prior to fetching the page, like so:

    http_o x;
    x.set_header_url("/search/sof");
    x.do_get_request();

You can specify the order in which GET items (eg, "Accept:", "User-Agent:", "Referer:", "Cookie:") can appear in the final text sent to a server by providing a 'struct z_keyval' array (defined in 'z_types.h'). The 'val' (string pointer) points to the item name (like in the parenthesized list above). The order in which they appear in the array is the order they will appear in the final GET request block. the 'val' [integer] value provided to the member function 'set_getitem_order()' is ignored. Internally, it has the following meanings: 0: the item is optional; 1: the item is required. During processing, 2 is added to this value. a value of 2-3 indicates the item has been added into the GET request block. After processing, 2 is subtracted from the value, restoring it to its original value.

member functions (primary)

http_o()
SIGNATURE: http_o ()
SYNOPSIS:
creates a a new simple HTTP object. All internal variables are in an "empty", initial state. The object has no assigned port number or connectivity.
 

http_o(<args>)
SIGNATURE: http_o (const string_o &shost, const int port = 80)
SYNOPSIS:
constructor that sets up the host and port (connect-to) information. This conveniently combines the default constructor, set_host(), and set_port().
PARAMETERS

• shost: the host computer to use for this object. This should be the same value as what would be used in the set_host() member function call (Please see the reference entry for that function for more information on host names).
• port: the port to connect to the web site. This argument is optional, it defaults to www's standard port number 80.

 

destructor
SIGNATURE: ~http_o ()
SYNOPSIS: virtual destructor. The HTTP object instance is wiped out and all contents are set to the at-construction state.
 

do_help()
SIGNATURE: boolean do_help (int *plev = NULL) const
SYNOPSIS: informational: if return value is 1, a help message is desired. the program should then exit.
PARAMETERS

plev: an optional [output] variable that tells what "detail level" of help is desired:
0: none - the command-line had no "help" parameters;
1: brief ("-h") - display a summary list of command- line parameters (and exit)
2: long version
3: full help - provide the user with a lot of info

DESCRIPTION: if this function returns TRUE, the program is to display help, and exit with exit code 0.
RETURNS:
TRUE: help is needed/wanted. show help message and exit.
FALSE: no help wanted
 

is_runparam()
SIGNATURE: boolean is_runparam (const char *str, boolean &warg, int *xtra = NULL, int *pi = NULL)
SYNOPSIS:
This routine tests if argument is one of the standard command-line parameters, to be processed by rundriver_o::cmdline(). This is convenient for child (eg, sub-) classes to check if their unknown command-line parameters are illegal or standard ones. This function is static, so it must not be used with an object instance.
example:
boolean boo = rundriver_o::is_runparam ("help"); if (!boo) { /* not a rundriver parameter; could be illegal */ }
PARAMETERS

• str: the string (from argv[]). The text in "str" may include a leading dash ('-') or slash ('/') character. A "dash" is the Vettrasoft-standard leading character for command-line options; however, a slash is also allowed for the rundriver object.
• warg: [required output] boolean variable, tells if the parameter specified by "str" takes an an argument. If "str" is invalid, "warg" is set to FALSE.
  example:
  boolean got_arg, is_parm;
  is_parm = is_runparam("vol", gotarg);
  In this case, both "is_parm" and "got_arg" are TRUE, since "vol" is a rundriver command-line argument, and it requires a value (which would immediately follow "-vol" on the command-line).
• xtra: [optional output] variable type indicator flag. values:
  0: a 'core' standard rundriver_o parameter
  1: an 'extended' rundriver_o parameter (eg, such as for database-oriented operations)
• pi: [optional output] error indicator flag. values:
  0: ok; variable is a valid rundriver object parameter;
  1: variable is not a rundriver object parameter;
  2: NULL pointer (application error);
  3: "str" is a dash ('-') only {munged input data).

RETURNS:
TRUE: command-line argument belongs to rundriver_o.
FALSE: argument is not known to rundriver_o (either application-specific, or errant).
 

cgiparams()
SIGNATURE: string_o cgiparams (int *pi = NULL)
SYNOPSIS: (WIP)
RETURNS: (WIP)
 

set_port()
SIGNATURE: int set_port (int)
SYNOPSIS: [WIP]
 

set_host()
SIGNATURE: int set_host (const string_o &h)
SYNOPSIS:
The value of 'h' should be the host computer the HTTP request is to be sent to. This is typically the "base" or "host" part of a URL, before any file path or query string. For example, given this URL:
http://ames.craigslist.org/search/jjj?query=c%2B%2B&srchType=T
The "host" component is "ames.craigslist.org". This value goes directly, as-is, into the HTTP "Host:" header entry.
 

set_url()
SIGNATURE: int set_url (const string_o &)
SYNOPSIS: [WIP]
 

set_file()
SIGNATURE: int set_file (const string_o &)
SYNOPSIS: [WIP]
 

entire_response()
SIGNATURE: const string_o &entire_response (int *pi = NULL) const
SYNOPSIS: (WIP)
 

url()
SIGNATURE: string_o url (int *pi = NULL) const
SYNOPSIS: [WIP]
TRAITS: this is an inline function
 

server_file()
SIGNATURE: string_o server_file (int *pi = NULL) const
SYNOPSIS: [WIP]
 

req_version()
SIGNATURE: string_o req_version (int *pi = NULL) const
TRAITS: inline function.
 

response_text()
SIGNATURE: const string_o &response_text (int *pi = NULL) const
SYNOPSIS: [WIP]
 

response_code()
SIGNATURE: int response_code (int *pi = NULL) const
SYNOPSIS: [WIP]
 

response_item()
SIGNATURE: string_o response_item (const string_o &s, int *pi = NULL) const
SYNOPSIS: [WIP]
 

set_version()
SIGNATURE: int set_version (const string_o &)
SYNOPSIS: [WIP]
 

set_referer()
SIGNATURE: int set_referer (const string_o &, int *pi = NULL)
SYNOPSIS: [WIP]
 

set_boundary()
SIGNATURE: int set_boundary (const string_o &, int *pi = NULL)
SYNOPSIS: [WIP]
 

set_cgiparams()
SIGNATURE: int set_cgiparams (paramstring_o &, boolean = FALSE, int *pi = NULL)
SYNOPSIS: (WIP)
 

set_writedelay()
SIGNATURE: int set_writedelay (const int x)
SYNOPSIS:
sets the delay between the moment of opening the connection to the server and sending the data to the server. The time is in milliseconds.
 

set_cgiparamstr()
SIGNATURE: int set_cgiparamstr (const string_o &)
SYNOPSIS: ((WIP))
 

set_cookie()
SIGNATURE: int set_cookie (const rec_dbag_o &d, int *pi)
SYNOPSIS:
this allows you to replace the object's cookie information with your own, The databag parameter 'd' must conform to the structure used to store cookie information. This function is to be used prior to invoking do_request(). The cookie data specified in 'd' will be used instead of any existing data (typically from a previous do_request() call).
The data bag format for 'd' is as follows:

cookie
(
    nameval
    (
        (name1 value1)
    )
    path    ""
    domain  ""
    expires ""
)

where 'nameval' contains a list of [1 or more] simple databags. 'name1' and 'value1' can and should be set to whatever name and value is desired. Here is an example:

cookie
(
    nameval
    (
        (cl_b   SnNSZDFd4hGo5qRIIPz5zAlfRi7)
        (__utmb "140029553.1.10.1331946082")
        (name3  value3)
    )
    path    "/"
    domain  ".craigslist.org"
    expires "Fri, 01-Jan-2038 00:00:00 GMT"
)

PARAMETERS

• d: a recursive databag containing information about the cookie. All fields in 'd' can be empty, except for the first simple databag in the 'nameval' list. The databag must conform to the structure outlined here. Actually, only the top-level name ("cookie") and "nameval" (with at least 1 name-value pair) are required. Here is the minimal data required:
  

  cookie
  (
      nameval
      ( 

• (name value) ) ) All missing data will simply be ignored. If the data item has an existing value, it will not be wiped out. To do so, the item must be included in databag 'd', with an empty string value (eg, "").
• pi: error [output] indicator variable. values:
  0: cookie data successfully updated
  zErr_Param_BadFormat: the given data (in 'd') was not properly formatted

RETURNS:
0: operation completed successfully
-1: error occurred; see value of 'pi' for reasons why.
 

clear_cookie()
SIGNATURE: int clear_cookie ()
SYNOPSIS: resets all cookie information. The internal value is_set is set to NO.
 

reset()
SIGNATURE: int reset ()
SYNOPSIS: ((WIP))
 

do_get_request()
SIGNATURE: int do_get_request (int *pi = NULL)
SYNOPSIS: ((WIP))
TRAITS: an inline function.
 

do_post_request()
SIGNATURE: int do_post_request (int *pi = NULL)
SYNOPSIS: ((WIP))
TRAITS: inline function.
 

do_multiform_post_request()
SIGNATURE: int do_multiform_post_request (int *pi = NULL)
SYNOPSIS: ((WIP))
TRAITS: inline function.
 

do_request()
SIGNATURE: int do_request (int kind, int *pi = NULL)
SYNOPSIS: this builds the (GET or POST) request string, sends it to the target host, and processes the host's reply.
PARAMETERS

• kind: the "kind" of request. this is a hard-coded value, one of the following:
  0: a GET request;
  1: a POST request;
  2: a GET request, but only the main URL line is constructed. 2 blank lines ("&bs;r&bs;n") are tacked on to the tail end.
• pi: error [output] indicator variable. values:
  0: successful traversal;
  1: URL has not been set earlier, by user;
  2: problem in setting up "GET" text block;
  3: error on socket opening;
  4: error trying to connect to web site;
  5: error while writing out to socket channel;
  6: parse-reply error: no header found;
  7: parse-reply error: no '/' found;
  8: parse-reply error: no ':' found on the header name keyword;
  9: unknown header keyword encountered;
  99: Unknown error.

RETURNS:
0: operation completed successfully
-1: error occurred; see value of 'pi' for reasons why.
 

cycle_thru_redirects()
SIGNATURE: int cycle_thru_redirects (int *pi = NULL)
SYNOPSIS: ((WIP))
 

key_value()
SIGNATURE: int key_value (const string_o &, string_o &, int *pi = NULL)
SYNOPSIS: ((WIP))
 

build_top_line()
SIGNATURE: string_o build_top_line (int, int *pi = NULL)
SYNOPSIS: ((WIP))
PARAMETERS

pi: error [output] indicator variable. values:
0: successfully ..

 

zis_cookie_reservedname()
SIGNATURE: boolean zis_cookie_reservedname (const string_o &s, boolean &w_param)
SYNOPSIS:
this function is very closely related to http_o, but exists as a standalone function. It returns TRUE if 's' is a "reserved word" in the list of values returned from a web server. Reserved words include "Expires", "Secure", "HttpOnly", "Domain", and "Path". If the word takes an argument, 'w_param' is set to TRUE. If not, it is FALSE.
 

note.
the helper class 'http_getreq_o' supports the http_o class and manages setting up a GET request text block.

you can define up to zMax_http_GETitems (64) items in the string array passed as input to 'http_getreq_o::set_getitem_order()'. the last array element must be NULL and the item count (the 2nd parameter to 'set_getitem_order()') must match the list count.

for GET requests, the "url head" defaults to "/".

understanding the http_o flag values.

• zfhttp_EXPLICIT_URL if this flag is set, 'zfhttp_USE_CGIPARAM_MATRIX' should be unset. this flag is set when set_header_url() or http_o::include_url_1stline() is called.
• zfhttp_USE_CGIPARAM_MATRIX if this flag is set, 'zfhttp_EXPLICIT_URL' should be unset. this flag is set by default. it is also set if http_o::set_cgiparams() is called and cleared when http_o::set_cgiparamstr() is called.
• zfhttp_CVT2CGI_ONFETCH this flag is set when calling "http_o::set_cgiparams(ps, TRUE)" the 2nd parameter means that the text in 'ps' is in "normal", raw format - the spaces in the text have not been converted to '+' characters, which is necessary in URLs. . if this flag is set, then z_string_to_cgistring() will be applied to the text inside http_o::build_cgi_paramline().
• zfhttp_GOT_REPLY_DATA
• zfhttp_ERROR_IF_UNIDENTIFIED
• zfhttp_USE_CGIPARAM_MATRIX
• zfhttp_CVT2CGI_ONFETCH
• zfhttp_BLOCK_FOR_RESPONSE the code for this flag is broken. it is permanently shut off.
• zfhttp_EXPLICIT_URL
• zfhttp_FOLLOW_REDIRECTS

examples.
The following example(s) are minimal, but should get you started:

#include "stdafx.h"
#include "z_http.h"
#include <iostream>

int main (const int argc, const char *argv[])
{
    int ie0, ie1, ie2;
    http_o x("api.ipinfodb.com", 80);

    ie1 = x.set_host ("ames.craigslist.org");           // NEW HOST!
    ie1 = x.set_url  ("ames.craigslist.org/search/sof");
    ie1 = x.set_cgiparamstr ("query=+&srchType=A&addOne=telecommuting");
    ie1 = x.do_request (0, &ie2);
    if (!ie1)
    {
        std::cout << "WEB SERVER RESPONSE:\n";
        std::cout << x.entire_response() << "\n\n";
    }

    return 0;
}