TinyPoker

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 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 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 subversion repository or by downloading the latest release.

Build and Install libtinypoker

Example: 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.

Example: 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).

Example: 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.

Example: 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.