Overview
--------

T3Net provides code for interacting with a web site from a native program.
T3Net can take specifically formatted data and parse it into easily usable
data sets. It uses curl or libcurl to handle HTTP(S) requests to ferry data
between a web site and a native application.


The C Side
----------

To set up T3Net, you must first initialize it with one of the HTTP(S) handlers.
Call 't3net_setup_with_curl()' to use the system's build-in (or bundled) curl
utility. Call 't3net_setup_with_libcurl()' to use libcurl.

Now you can utilize 't3ned_download()' to download data/files or
't3net_get_data()' to get a 'T3NET_DATA' data set. For example, If you are
retrieving a list of high scores, for instance, you can do something like this:

T3NET_DATA * score_list;
int i;
const char * val;

score_list = t3net_get_data(url_to_score_script, NULL, NULL);
if(score_list)
{
    for(i = 0; i < score_list->entries; i++)
    {
        name = t3net_get_data_entry_field(score_list, i, "name");
        val = t3net_get_data_entry_field(score_list, i, "score");
        if(name && val)
        {
            printf("%d. %s - %s\n", i + 1, name, score);
        }
    }
}


C API Reference
---------------

t3net_download(const char * url,
               T3NET_ARGUMENTS * arguments,
               T3NET_POST_DATA * post_data,
               const char * out_path
               char * error_out,
               int error_size):

  This function takes 4 arguments. 'url' is the base URL. 'arguments' are the
  arguments that will be passed through the URL. 'post_data' is the form data
  that will be sent through HTTP POST data. 'out_path' is the path to where the
  data will be downloaded. 'error_out' is used to store the error message if
  the download fails. 'error_size' is the size of 'error_out'. See below for
  info on how to construct arguments and POST data.


t3net_get_data(const char * url,
               T3NET_ARGUMENTS * arguments,
               T3NET_POST_DATA * post_data):

  This function takes 3 arguments. 'url' is the base URL. 'arguments' are the
  arguments that will be passed through the URL. 'post_data' is the form data
  that will be sent through HTTP POST data. See below for info on how to
  construct arguments and POST data.


T3NET_ARGUMENTS * t3net_create_arguments(void):

  Create an empty arguments list.


t3net_add_argument(T3NET_ARGUMENTS * arguments,
                   conat char * key,
                   const char * val):

  Add an argument to an arguments list.


t3net_destroy_arguments(T3NET_ARGUMENTS * arguments):

  Destroy an arguments list (free it's allocated memory).


T3NET_POST_DATA * t3net_create_post_data(void):

  Create a POST data list.


t3net_add_post_data(T3NET_POST_DATA * poar_data,
                    conat char * key,
                    const char * val):

  Add POST data to a POST data list.


t3net_destroy_post_data(T3NET_POST_DATA * post_data):

  Destroy a POST data list (free it's allocated memory).


const char * t3net_get_data_entry_field(T3NET_DATA * data,
                                        int entry,
                                        const char * field_name);

  Retrieve a value from a data set. Returns 'NULL' if no matching data was
  found.


The PHP Side
------------

A template is provided to help you get started. T3Net expects your script to
output data in this format:

Example Header\r\n
\r\n
\tfield_name_1: data1\r\n
\tfield_name_2: data2\r\n
\r\n
\tfield_name_1: data3\r\n
\tfield_name_2: data4\r\n

The script is self-explanatory. You just need to put in the correct database
info and make the data in the arrays match what is in your database.

Let's say you have a database with this structure:

my_dabatase
-leaderboards
 -game
 -name
 -score

The database in the script should be set up like this:

$db_database = "my_database";
$db_name = "leaderboards";
$db_fields = array('game', 'name', 'score');

The output section should be set up like this:

$output_fields = array('name', 'score');

The settings should be set up like this:

$order_field = "score";

When you access this script through T3Net with the URL like this:

score_list = t3net_get_data("http://www.site.com/my_script.php?game=my_game");

you will get a data set containing all of the scores in the database where the
game field is set to "my_game" in order form highest to lowest.

You can change how the data is generated by passing arguments in the URL:

score_list = t3net_get_data("http://www.site.com/my_script.php?game=my_game&ascend=true&limit=10");

This set of arguments will sort the scores from lowest to highest and only
output 10 entries.