mcs-client

## mcs-client mcs-client — MCS client interface (for applications) |

## Synopsis

                        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

### McsClient

    typedef struct _McsClient 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.