Client Code Overview

From Mugshot Developer Wiki

Overview of the code implementing the Windows and Linux clients.

To compile these clients see Linux Client Development Setup and Windows Client Development Setup.

When working on these clients, use the C Style Guide.

Contents 1 Common Cross-Platform Library 2 Linux Client 3 Windows Client 4 Browser Connection 5 Approach to Portability

Common Cross-Platform Library

If you check out trunk/client you'll see three directories

• client/common
• client/linux
• client/windows

Shockingly, client/common contains the shared cross-platform parts, while the other two contain the platform-specific frontends.

client/common is based on GLib and GObject and is written in C. It uses the Loudmouth XMPP implementation.

Some important files in the common library:

• hippo-connection.[hc] contains the XMPP protocol implementation
• hippo-data-cache.[hc] contains the "model" the client maintains of server-side state
• hippo-basics.[hc] is one of those unfortunate "utils" files with a grab-bag of random stuff; it should probably be split up a little. But it has a lot of cross-platform utility routines including the command line option parser.
• <hippo/hippo-common.h> is the file you're supposed to include to use the library

Linux Client

The Linux client is in C and uses GObject, just like the common library. It also uses GTK for graphics, libcurl for HTTP requests, and GConf for preferences.

To figure it out, start in trunk/client/linux/src/main.c - in general the Linux client is straighforward.

Some of the notable bits:

• On Windows there's an ActiveX control that lets the server-provided JSP pages interact with the client. On Linux, we are instead using a protocol handler for special "mugshot:" links. See linux/src/uri-handler.c
• D-BUS is used to ensure only one client exists per Mugshot server
• D-BUS is also used to watch for new tracks played in Rhythmbox
• The client creates a tray icon using a cut-and-pasted copy of GtkStatusIcon from GTK 2.9.x
• The bubble notifications from the tray icon use a custom widget in hippo-bubble.c - this is essential for SWARMY ORANGENESS
• It will currently look for your mugshot.org login cookie in the Epiphany and Firefox cookies files; if you're using another browser, it won't work, though it's probably easy to add support

Windows Client

The Windows client core logic is almost entirely C++, with most of the visible user interface rendered with an embedded Internet Explorer, using HTML and JavaScript.

If you open up the project in Visual Studio, you'll see a number of different modules. The most important one is HippoUI, which contains the majority of the code. It is responsible for managing components like the chat window, notification bubbles, keeping track of browser URLs for sharing, etc. Highlight classes of HippoUI are:

• HippoUI: Primarily a glue class. It receives input from the IM layer and browser

tracker and forwards the events around as needed.

• HippoBubble: Embeds an instance of HippoIE to display the link swarm bubbles.
• HippoITunesMonitor: Tracks what iTunes is playing, to implement the music embed.
• HippoMenu: What's shown when you click on the tray icon.

The HippoExplorer project implements the Internet Explorer embedded control. Its major tasks are to monitor IE instances and forward URL changes to HippoUI (via COM), and also to implement the "framer" that appears when you visit an URL. Classes include:

• HippoTracker: Monitors IE URL changes.
• HippoEmbed: An ActiveX control, which provides the bridge between web pages from

the server and access to the client. For example, chat messages are received via XMPP, then broadcast from this control to listening JSP web pages recieved from the server.

• HippoExplorer: Implements the framer display.

Finally HippoUtil is a collection of general library code. Some of it is thin wrappers over existing library calls, while other components can be fairly complex. Some classes in this project are:

• HippoUtil.h: A pure header file which contains the implementation of HippoPtr and HippoBSTR,

two classes you will see used very frequently.

• HippoIE: Implements an embedded Internet Explorer control. This class handles some bizarre quirks of IE,

and also makes it convenient to do things like invoke JavaScript. Used extensively.

• HippoConnectionPoint and HippoConnectionPointContainer: Utility classes for implementing and

using COM objects.

Browser Connection

A lot of the interesting things that happen on the site involve the client interacting with the web pages. For example, we show a live preview of recent chat comments on the framer page that we display beneath a shared web page; to do this, we have browser plugins for IE and Firefox that communicate with the client over D-BUS (on Linux) or COM (on Windows). This is gone into in a lot of detail in Client Javascript Connection, but some of the code pieces of this you might see are:

• libhippoipc - A small library that defines logic for connecting multiple web pages onto a single connection to the client. This defines:
  • HippoIpcProvider: abstract base class for talking "upstream" to the client. Has subclasses HippoDBuspIpcProvider, HippoComIpcProvider
  • HippoIpcListener: abstract base class for talking "downstream" to one of the web pages
  • HippoIpcController: concrete class that knows how to hook many HippoListeners onto one HippoProvider
• In libhippo
  • HippoIpcSource: GObject that connects to the data model and tracks what signals need to be sent to which web page objects

Approach to Portability

Mugshot shares the "backend" across platforms, but the "frontend" is coded separately for each platform.

There are a few reasons for this:

• The Mugshot client is a set of desktop and application extensions, and these are fundamentally unportable and could not be done in a cross-platform way anyhow. Mugshot isn't an application in the sense of a word processor or something.
• When we can, we tend to just use a web page; this is why the client is all plugins and extensions, because those things can't be done web-based.
• We think native applications offer a nicer user experience.
• For an open source project, maintaining separate frontends isn't that big a deal, assuming the frontends are for platforms somebody cares about.

The common library could definitely be a larger percentage of the codebase than it is, though; we appreciate patches to refactor common logic down into the common library.