// TinyPoker.org
// Copyright (C) 2007, 2008, 2009, 2010 Thomas Cort <linuxgeek@gmail.com>
//
// Permission is granted to copy, distribute and/or modify this document
// under the terms of the GNU Free Documentation License, Version 1.3 or
// any later version published by the Free Software Foundation; with no
// Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
// copy of the license is included in the section entitled "GNU Free
// Documentation License".

libtinypoker application programming interface
==============================================

*libtinypoker* provides application programming interfaces
(APIs) to applications implementing the Internet Poker Protocol (IPP)
Version 2.0. IPP message validation, normalization and parsing functions
are available to developers as are several predefined types for
representing poker games, players and cards.

This document will descibe how to use *libtinypoker* in your applications.
The document also covers installing the library itself. Please read and
make sure you understand the link:agpl-3.0.html[license]
before proceeding.

Install the Dependencies
------------------------

TinyPoker makes use of several software libraries. Each one must be installed
before building and running *tinypokerd*. A complete list can be found on the
link:download.html[download] page.

Obtain the Source Code
----------------------

The next step is to get a copy of the *libtinypoker* source code.
This can be done by checking out a fresh copy from the http://subversion.tigris.org/[subversion]
link:subversion.html[repository] or by
link:download.html[downloading] the latest release.

Build and Install libtinypoker
------------------------------

.Configure, make, test, and install
--------------------------------------
 $ cmake -D CMAKE_INSTALL_PREFIX=/usr .
 $ make
 $ make test
 # make install
--------------------------------------

Library Initialization and Destruction
--------------------------------------

Several glib resources need to be allocated before network
communications begin and deallocated after network connications
end. Two functions are provided to accomplish this, *ipp_init()*
and *ipp_exit()*. Additionally, the random number generator is
allocated and freed in those functions. The one and only header file 
needed to use the API is *tinypoker.h*.

What follows is an example that simply initializes and cleans up
after *libtinypoker*.

.test.c
------------------------------------------
#include <tinypoker.h>

int main(int argc, char *argv[]) {
	ipp_init();

	ipp_exit();
	return 0;
}
------------------------------------------

Compilation
-----------

Compiling a *libtinypoker* application is relatively simple.
One simply needs to instruct the compiler to link against the
library and glib.

------------------------------------------
 $ gcc -ltinypoker -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -lglib-2.0 -o test test.c
------------------------------------------

Shaking hands with the Server
-----------------------------

The protocol calls for a handshake to happen between the client and
the server. During the handshake the client connects, the server notifies
the client of the supported protocol version, the client response with a
buy in request and the server responds with a welcome message.

This can be done manually with a connect, a read, a send and another
read. Since the code is 25+ lines and since every client application
will need to do this, *libtinypoker* provides a helper function (demonstrated
below).

.test.c
------------------------------------------
#include <tinypoker.h>

int main(int argc, char *argv[]) {
	ipp_socket *sock;

	ipp_init();

	sock = ipp_client_handshake("localhost", 9898, "JSMITH", "ABC123", "500", NULL);
	if (!sock) {
		ipp_exit();
		return 1;
	}

	ipp_disconnect(sock);
	ipp_free_socket(sock);
	sock = NULL;

	ipp_exit();
	return 0;
}
------------------------------------------

Protocol Logging
----------------

Having access to the payload (text string) of every message that gets
sent or recieved is useful for debugging. Each message could also be
saved to a file for analysis and statistics gathering. Therefore,
the send and read functions have a protocol logger callback. You can
create your own logging function like the one below.

.test.c
------------------------------------------
#include <tinypoker.h>

void protocol_logger(char *msg) {
	if (msg && msg[0]) {
		printf("%s\n", msg);
	}
}

int main(int argc, char *argv[]) {
	ipp_socket *sock;

	ipp_init();

	sock = ipp_client_handshake("localhost", 9898, "JSMITH", "ABC123", "500", protocol_logger);
	if (!sock) {
		ipp_exit();
		return 1;
	}

	ipp_disconnect(sock);
	ipp_free_socket(sock);
	sock = NULL;

	ipp_exit();
	return 0;
}
------------------------------------------

To be continued
---------------

This document is being written as this software is 
being developed, so it is still very much a work in progress. If you want
to go further, take a look at *tinypoker.h*; it is well commented and
should give you and idea about the functions and structures available.