mcs-client

mcs-client — MCS client interface (for applications)

Synopsis




struct      McsClient;
enum        McsAction;
void        (*McsNotifyFunc)                (const gchar *name,
                                             const gchar *channel_name,
                                             McsAction action,
                                             McsSetting *setting,
                                             void *cb_data);
void        (*McsWatchFunc)                 (Window window,
                                             gboolean is_start,
                                             long mask,
                                             void *cb_data);
McsClient*  mcs_client_new                  (Display *display,
                                             int screen,
                                             McsNotifyFunc notify,
                                             McsWatchFunc watch,
                                             void *cb_data);
void        mcs_client_destroy              (McsClient *client);
gboolean    mcs_client_process_event        (McsClient *client,
                                             XEvent *xev);
McsChannel* mcs_client_add_channel          (McsClient *client,
                                             const gchar *channel_name);
void        mcs_client_delete_channel       (McsClient *client,
                                             const gchar *channel_name);
McsResult   mcs_client_get_setting          (McsClient *client,
                                             const gchar *name,
                                             const gchar *channel_name,
                                             McsSetting **setting);
void        mcs_client_show                 (Display *display,
                                             int screen,
                                             const gchar *message);
gboolean    mcs_client_check_manager        (Display *display,
                                             int screen,
                                             const gchar *manager_command);

Description

The MCS client functions are intended to be called by applications that store settings via the MCS manager. The client functions are limited to querying and watching settings data; MCS clients are not capable of changing any settings.

Details

struct McsClient

struct McsClient;


enum McsAction

    typedef enum
    {
        MCS_ACTION_NEW,
        MCS_ACTION_CHANGED,
        MCS_ACTION_DELETED
    }
    McsAction;

A type used in the McsNotifyFunc to describe a settings event.

MCS_ACTION_NEWA new setting has been added to the channel.
MCS_ACTION_CHANGEDAn existing setting has changed.
MCS_ACTION_DELETEDA setting has been deleted from the channel.

McsNotifyFunc ()

void        (*McsNotifyFunc)                (const gchar *name,
                                             const gchar *channel_name,
                                             McsAction action,
                                             McsSetting *setting,
                                             void *cb_data);

A function of this type, passed to mcs_client_new() will be called when changes occur in channels that the MCS client is watching.

name :The name of the setting that is affected.
channel_name :The channel to which the setting belongs.
action :An McsAction describing the event.
setting :A pointer to the McsSetting that is affected.
cb_data :Callback data passed to mcs_client_new().

McsWatchFunc ()

void        (*McsWatchFunc)                 (Window window,
                                             gboolean is_start,
                                             long mask,
                                             void *cb_data);

window :The X window on which an event occurred.
is_start :
Param3 :
cb_data :Callback data passed to mcs_client_new().

mcs_client_new ()

McsClient*  mcs_client_new                  (Display *display,
                                             int screen,
                                             McsNotifyFunc notify,
                                             McsWatchFunc watch,
                                             void *cb_data);

Creates a new client connection to the MCS manager running on display and screen.

display : The X display on which the MCS manager is running.
screen : The X screen on which the MCS manager is running.
notify : A McsNotifyFunc to call when changes occur in MCS channels.
watch : A McsWatchFunc to call when (something happens).
cb_data : A pointer to data to pass to the notify and watch functions.
Returns : A new McsClient.

mcs_client_destroy ()

void        mcs_client_destroy              (McsClient *client);

Frees all resources associated with client.

client : An McsClient.

mcs_client_process_event ()

gboolean    mcs_client_process_event        (McsClient *client,
                                             XEvent *xev);

FIXME: Fill me in!

client : An McsClient.
xev : An XEvent to process.
Returns : True if something happens, FALSE otherwise.

mcs_client_add_channel ()

McsChannel* mcs_client_add_channel          (McsClient *client,
                                             const gchar *channel_name);

Adds a channel to be monitored by client. This must be called before any settings changes in that channel will cause the McsNotifyFunc (passed to mcs_client_new()) to be called.

client : An McsClient.
channel_name : The name of the channel to add.
Returns : A pointer to the McsChannel referenced.

mcs_client_delete_channel ()

void        mcs_client_delete_channel       (McsClient *client,
                                             const gchar *channel_name);

Removes channel_name from the list of channels that client is watching. The client will no longer receive notifications of settings changes in this channel.

client : An McsClient.
channel_name : The name of a channel this McsClient is watching.

mcs_client_get_setting ()

McsResult   mcs_client_get_setting          (McsClient *client,
                                             const gchar *name,
                                             const gchar *channel_name,
                                             McsSetting **setting);

Retrieves setting name from channel channel name. The result is placed in setting and should be freed with mcs_setting_free().

client : An McsClient.
name : The name of a setting.
channel_name : The name of the channel in which to look for name.
setting : A pointer to a McsSetting structure.
Returns : MCS_SUCCESS on success, or another McsResult representing an error that occurred.

mcs_client_show ()

void        mcs_client_show                 (Display *display,
                                             int screen,
                                             const gchar *message);

Instructs the MCS manager to show the settings dialog for the module specified in message.

display : The X display on which the MCS manager is running.
screen : The X screen on which the MCS manager is running.
message : The module to show.

mcs_client_check_manager ()

gboolean    mcs_client_check_manager        (Display *display,
                                             int screen,
                                             const gchar *manager_command);

Checks to see if an MCS manager is running on display and screen. If not, tries to execute manager_command.

display : The X display on which the MCS manager may be running.
screen : The X screen on which the MCS manager may be running.
manager_command : A command to execute.
Returns : TRUE if the MCS manager is running, FALSE otherwise.