---
name: "libhandoff"
section: "3"
platform: "linux"
package: "libhandoff-dev"
version: "0.1-5"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/libhandoff"
---

# libhandoff(3)

handoff library for GPE calendar.

## NAME

libhandoff - handoff library for GPE calendar.

## SYNOPSIS

**extern GType handoff\_get\_type(void);**

**typedef void (\*HandoffCallback)(Handoff** *\*handoff***, char \*** *data***);**

**extern Handoff \* handoff\_new(void);**

**extern gboolean handoff\_handoff(Handoff \****handoff***, const char \****rendezvous***, const char \****data***, gboolean** *display\_relevant***,** *char \*(\*serialize) (Handoff \*)***,** *void (\*exit)(Handoff \*)***);**

## DESCRIPTION

This manual page briefly describes the *libhandoff0* API.

This manual page was written for the Debian distribution because the original program does not have a manual page.

*libhandoff* is used in the GPE Palmtop Environment to cause another program instance to come to the foreground. This is used when alarm triggers (like atd) wake the device and then need to load another program to show the reason for the device waking up. When gpe-calendar starts it looks at a well known location to find another instance of itself. If it does, it tells that instance to grab the focus.

This man page is for *libhandoff0* version *0.1*.

## FUNCTIONS

The Handoff and HandoffClass structs are opaque. Use **handoff\_new** to return a new Handoff \* instance.

**typedef void (\*HandoffCallback)(Handoff** *\*handoff***, char \*** *data***);**

The "handoff" signal is triggered when another instance successfully negotiates a handoff to this instance. DATA is the data sent by other instance, normally a serialization of state this instance should use.

**extern Handoff \* handoff\_new(void);**

Create a new passive handoff. Before calling handoff\_handoff, the caller should connect a handler to the "handoff" signal.

**extern gboolean handoff\_handoff(Handoff \****handoff***, const char \****rendezvous***, const char \****data***, gboolean** *display\_relevant***,** *char \*(\*serialize) (Handoff \*)***,** *void (\*exit)(Handoff \*)***);**

Try to handoff this instance to an already running process.

*rendezvous* is the address which all instances of this program rendezvous with.

If another instance of the program is contacted then: if *display\_relevant* is true, the value of the environment variable DISPLAY is sent; and if *data* is non-NULL, its value is sent. If the handoff request (DISPLAY is either not sent or they are identical), this function returns TRUE and this instance should proceed to exit. Otherwise, if the other instance punts, it sends a serialization of its state and the "handoff" signal is fired and TRUE is returned.

If no running instance is found to be listening on *rendezvous* or the instance punts, this instance attempts to bind to *rendezvous* so that subsequent instances can find this instance and FALSE is returned.

After connecting, this instance waits on *rendezvous* for other instances to connect. When an instance connects and hands off its state, the "handoff" signal is fired. If this instance decides to yield (based on the above criteria), then *serialize* is called to serialize any state. Once the handoff completes, *exit* is called and this instance should proceed to do any final clean up and exit.

## AUTHOR

This manual page was written by Neil Williams \<linux@codehelp.co.uk\> for the Debian system (but may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL.