libhandoff(3) [debian man page]
LIBHANDOFF0(3) Copyright FSF 1996-2006 LIBHANDOFF0(3) 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. libhandoff 3 Wed 25 Apr 2007 10:58:46 BST LIBHANDOFF0(3)
Check Out this Related Man Page
smf_enable_instance(3SCF) Service Configuration Facility Library Functions smf_enable_instance(3SCF) NAME
smf_enable_instance, smf_disable_instance, smf_refresh_instance, smf_restart_instance, smf_maintain_instance, smf_degrade_instance, smf_restore_instance, smf_get_state - administrative interface to the Service Configuration Facility SYNOPSIS
cc [ flag... ] file... -lscf [ library... ] #include <libscf.h> int smf_enable_instance(const char *instance, int flags); int smf_disable_instance(const char *instance, int flags); int smf_refresh_instance(const char *instance); int smf_restart_instance(const char *instance); int smf_maintain_instance(const char *instance, int flags); int smf_degrade_instance(const char *instance, int flags); int smf_restore_instance(const char *instance); char *smf_get_state(const char *instance); DESCRIPTION
These functions provide administrative control over service instances. Using these functions, an administrative tool can make a request to enable, disable, refresh, or restart an instance. All calls are asynchronous. They request an action, but do not wait to see if the action succeeds or fails. The smf_enable_instance() function enables the service instance specified by instance FMRI. If flags is SMF_TEMPORARY, the enabling of the service instance is a temporary change, lasting only for the lifetime of the current system instance. The flags argument is set to 0 if no flags are to be use. The smf_disable_instance() function disables the service instance specified by instance FMRI. If flags is SMF_TEMPORARY, the disabling of the service instance is a temporary change, lasting only for the lifetime of the current system instance. The flags argument is set to 0 if no flags are to be use. The smf_refresh_instance() function causes the service instance specified by instance FMRI to re-read its configuration information. The smf_restart_instance() function restarts the service instance specified by instance FMRI. The smf_maintain_instance() function moves the service instance specified by instance into the maintenance state. If flags is SMF_IMMEDI- ATE, the instance is moved into maintenance state immediately, killing any running methods. If flags is SMF_TEMPORARY, the change to main- tenance state is a temporary change, lasting only for the lifetime of the current system instance. The flags argument is set to 0 if no flags are to be use. The smf_degrade_instance() function moves an online service instance into the degraded state. This function operates only on instances in the online state. The flags argument is set to 0 if no flags are to be use. The only available flag is SMF_IMMEDIATE, which causes the instance to be moved into the degraded state immediately. The smf_restore_instance() function brings an instance currently in the maintenance to the uninitialized state, so that it can be brought back online. For a service in the degraded state, smf_restore_instance() brings the specified instance back to the online state. The smf_get_state() function returns a pointer to a string containing the name of the instance's current state. The user is responsible for freeing this string. Possible state strings are defined as the following: #define SCF_STATE_STRING_UNINIT ((const char *)"uninitialized") #define SCF_STATE_STRING_MAINT ((const char *)"maintenance") #define SCF_STATE_STRING_OFFLINE ((const char *)"offline") #define SCF_STATE_STRING_DISABLED ((const char *)"disabled") #define SCF_STATE_STRING_ONLINE ((const char *)"online") #define SCF_STATE_STRING_DEGRADED ((const char *)"degraded") RETURN VALUES
Upon successful completion, smf_enable_instance(), smf_disable_instance(), smf_refresh_instance(), smf_restart_instance(), smf_main- tain_instance(), smf_degrade_instance(), and smf_restore_instance() return 0. Otherwise, they return -1. Upon successful completion, smf_get_state returns an allocated string. Otherwise, it returns NULL. ERRORS
These functions will fail if: SCF_ERROR_NO_MEMORY The memory allocation failed. SCF_ERROR_INVALID_ARGUMENT The instance FMRI or flags argument is invalid. SCF_ERROR_NOT_FOUND The FMRI is valid but there is no matching instance found. SCF_ERROR_CONNECTION_BROKEN The connection to repository was broken. SCF_ERROR_NO_RESOURCES The server has insufficient resources. The smf_restore_instance() and smf_degrade_instance() functions will fail if: SCF_ERROR_CONSTRAINT_VIOLATED The function is called on an instance in an inappropriate state. The scf_error(3SCF) function can be used to retrieve the error value. ATTRIBUTES
See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |Interface Stability |Evolving | +-----------------------------+-----------------------------+ |MT-Level |Safe | +-----------------------------+-----------------------------+ SEE ALSO
libscf(3LIB), scf_error(3SCF), attributes(5) SunOS 5.10 9 Sep 2004 smf_enable_instance(3SCF)