Client Application Tutorial

Creating Client Applications — A basic tutorial explaining the use of the GTcpConnection object for applications.

Introduction

The GTcpConnection object provides an easy-to-use system for handling TCP/IP connections. It was intended to be used in network-oriented GUI applications, and provides utilities and features for that purpose. This tutorial covers linking to GTcpSocket and a basic means of using of the GTcpConnection object.

Compiling

The first order of business is getting your application or library to link to the GTcpSocket library. This section assumes that your system has pkg-config installed.

Pkg-config provides a means of including the proper compiling and linking flags for your application. It has macros for use in an autoconf/automake system as well as a basic command-line tool for use in a basic Makefile. The command-line tool can be used to include the compiling and linking flags needed for an application which uses LibGTcpSocket:

$ cc `pkg-config --cflags libgtcpsocket-1.0` -c main.c -o main.o
$ cc `pkg-config --libs libgtcpsocket-1.0` -o appname main.o

However, since most applications which use GTcpSocket will also use the autoconf/automake build system, using the autoconf macro inside configure.in makes more sense:

...
PKG_CHECK_MODULES(NETWORKING, libgtcpsocket-1.0 >= 1.0.0)
AC_SUBST(NETWORKING_CFLAGS)
AC_SUBST(NETWORKING_LIBS)
...

Then, in your source directory's Makefile.am:

...
target_CFLAGS = \
	$(NETWORKING_CFLAGS)

target_LIBS = \
	$(NETWORKING_LIBS)
...

That's it, that will automatically read and include the appropriate information needed to compile a program which uses GTcpSocket.

Programming

Since GTcpConnection is a GObject, you can sub-class it for the particular protocol you want to use. Subclassing GObjects is very easy once you're familiar with the process. For the purposes of this tutorial, imagine a protocol called "Wommft", a very basic file transfer protocol that has four commands, LOGIN, GET, PUT, and QUIT.

The first step is to define the the structure for the object:

typedef struct _WommftClient WommftClient;
typedef struct _WommftClientClass WommftClientClass;

struct _WommftClient
{
	GTcpConnection parent;

	gchar *username;
	gchar *passwd;

	/* The current file being transferred. */
	gchar *path;
	gsize offset;
};

struct _WommftClientClass
{
	GTcpConnectionClass parent_class;

	/* Signals */
	void (*download_start) (WommftClient *client, const gchar *path, gsize offset);
	void (*download_done) (WommftClient *client, const gchar *path, gboolean complete);
	void (*upload_start) (WommftClient *client, const gchar *path, gsize offset);
	void (*upload_done) (WommftClient *client, const gchar *path, gboolean complete);
};