## 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_NEW` | A new setting has been added to the channel.
`MCS_ACTION_CHANGED` | An existing setting has changed.
`MCS_ACTION_DELETED` | A 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.