## mcs-common

mcs-common — common MCS utility functions and types

## Synopsis

    struct      McsBuffer;
    struct      McsColor;
    struct      McsList;
    struct      McsChannel;
    struct      McsChannelList;
    struct      McsSetting;
    enum        McsType;
    enum        McsResult;
    enum        McsManagerCheck;
    McsManagerCheck mcs_manager_check_running   (Display *display,
                                                 int screen);
    McsSetting* mcs_setting_copy                (McsSetting *setting);
    void        mcs_setting_free                (McsSetting *setting);
    int         mcs_setting_equal               (McsSetting *setting_a,
                                                 McsSetting *setting_b);
    void        mcs_list_free                   (McsList *list);
    McsList*    mcs_list_copy                   (McsList *list);
    McsResult   mcs_list_insert                 (McsList **list,
                                                 McsSetting *setting);
    McsSetting* mcs_list_lookup                 (McsList *list,
                                                 const gchar *name);
    McsResult   mcs_list_delete                 (McsList **list,
                                                 const gchar *name);
    gchar       mcs_byte_order                  (void);
    #define     MCS_PAD                         (n,m)

## Description

## Details

### struct McsBuffer

    struct McsBuffer {

            gchar byte_order;
            size_t len;
            guchar *data;
            guchar *pos;
        };

A data storage buffer.

gchar `byte_order` | The btye ordering of data in the buffer.
size_t `len` | The length of data in the buffer.
guchar *`data` | A pointer to the data in the buffer.
guchar *`pos` | FIXME

### struct McsColor

    struct McsColor {

            guint16 red, green, blue, alpha;
        };

A structure representing a color value.

guint16 `red` | The color's red component.
guint16 `green` | The color's green component.
guint16 `blue` | The color's blue component.
guint16 `alpha` | The color's alpha (transparency) value.

### struct McsList

    struct McsList {

            McsSetting *setting;
            McsList *next;
        };

A singly-linked list structure containing McsSetting structs.

McsSetting *`setting` | The McsSetting in this list node.
McsList *`next` | A pointer to the next node in the list.

### struct McsChannel

    struct McsChannel {

            gchar *channel_name;
            Atom channel_atom;
            McsList *settings;
            gboolean raw;
            int ref_count;
        };

A representation of a settings channel.

gchar *`channel_name` | The name of the channel.
Atom `channel_atom` | FIXME
McsList *`settings` | A list of settings in the channel.
gboolean `raw` |
int `ref_count` | A reference count.

### struct McsChannelList

    struct McsChannelList {

            McsChannel *channel;
            McsChannelList *next;
        };

A singly-linked list structure containing McsChannel structs.

McsChannel *`channel` | The McsChannel in this list node.
McsChannelList *`next` | A pointer to the next node in the list.

### struct McsSetting

    struct McsSetting {

            gchar *name;
            gchar *channel_name;
            McsType type;

            union
            {
                int v_int;
                gchar *v_string;
                McsColor v_color;
            }
            data;

A structure representing a setting controlled by the MCS manager.

gchar *`name` | The name of the setting.
gchar *`channel_name` | The channel to which the setting belongs.
McsType `type` | The McsType of the setting.

### enum McsType

        typedef enum
        {
            MCS_TYPE_INT = 0,
            MCS_TYPE_STRING = 1,
            MCS_TYPE_COLOR = 2
        }
        McsType;

An enumerated type for MCS settings types.

`MCS_TYPE_INT` | The setting is an integer value.
`MCS_TYPE_STRING` | The setting is a string value.
`MCS_TYPE_COLOR` | The setting is an McsColor value.

### enum McsResult

        typedef enum
        {
            MCS_SUCCESS,
            MCS_NO_MEM,
            MCS_ACCESS,
            MCS_FAILED,
            MCS_NO_ENTRY,
            MCS_DUPLICATE_ENTRY,
            MCS_NO_CHANNEL
        }
        McsResult;

An enumerated type for detailing error conditions from MCS functions.

`MCS_SUCCESS` | The command commpleted successfully.
`MCS_NO_MEM` | The command failed due to an out-of-memory condition.
`MCS_ACCESS` | The command failed because you do not have the proper access privileges.
`MCS_FAILED` | The command failed for an unknown or generic reason.
`MCS_NO_ENTRY` | The command failed because no entry was found matching what you specified.
`MCS_DUPLICATE_ENTRY` | The command failed because an entry of that name already exists.
`MCS_NO_CHANNEL` | The command failed because the channel specified does not exist.

### enum McsManagerCheck

        typedef enum
        {
            MCS_MANAGER_NONE,
            MCS_MANAGER_STD,
            MCS_MANAGER_MULTI_CHANNEL,
            MCS_MANAGER_BOTH
        }
        McsManagerCheck;

An enumerated type detailing what kind of MCS manager is running.

`MCS_MANAGER_NONE` | No MCS manager is running.
`MCS_MANAGER_STD` | A standard MCS manager is running.
`MCS_MANAGER_MULTI_CHANNEL` | A multi-channel MCS manager is running.
`MCS_MANAGER_BOTH` | An MCS manager that supports both single- and multi-channel access is running.

### mcs_manager_check_running ()

    McsManagerCheck mcs_manager_check_running   (Display *display,
                                                 int screen);

Checks to see if there is an MCS manager running on `display` and `screen`.

`display` : | The X display on which the MCS manager may be running.
`screen` : | The X screen on which the MCS manager may be running.
Returns : | An McsManagerCheck value describing what kind of MCS manager (if any) is running.

### mcs_setting_copy ()

    McsSetting* mcs_setting_copy                (McsSetting *setting);

Makes a copy of `setting`. You should free the result with `mcs_setting_free()` when it is no longer needed.

`setting` : | An existing McsSetting.
Returns : | A new McsSetting, initialised to the value of `setting`.

### mcs_setting_free ()

    void        mcs_setting_free                (McsSetting *setting);

Frees all resources associated with `setting`.

`setting` : | An McsSetting.

### mcs_setting_equal ()

    int         mcs_setting_equal               (McsSetting *setting_a,
                                                 McsSetting *setting_b);

Checks to see if `setting_a` and `setting_b` represent the same setting data.

`setting_a` : | An McsSetting.
`setting_b` : | An McsSetting.
Returns : | `1` if the two settings are the same, `0` otherwise.

### mcs_list_free ()

    void        mcs_list_free                   (McsList *list);

Frees all memory associated with `list`.

`list` : | An McsList.

### mcs_list_copy ()

    McsList*    mcs_list_copy                   (McsList *list);

Makes a copy of `list`. You should free the result with `mcs_list_free()` when it is no longer needed.

`list` : | An existing McsList.
Returns : | A new McsList, initialised to the contents of `list`.

### mcs_list_insert ()

    McsResult   mcs_list_insert                 (McsList **list,
                                                 McsSetting *setting);

Inserts `setting` into `list`, updating the list pointer if necessary.

`list` : | A pointer to an existing McsList.
`setting` : | An McsSetting to insert into the list.
Returns : | `MCS_SUCCESS` if the item was successfully inserted.

### mcs_list_lookup ()

    McsSetting* mcs_list_lookup                 (McsList *list,
                                                 const gchar *name);

Looks for a setting with name `name` in the McsList.

`list` : | An McsList.
`name` : | The name of a setting.
Returns : | The corresponding McsSetting, or `NULL` if the setting was not found.

### mcs_list_delete ()

    McsResult   mcs_list_delete                 (McsList **list,
                                                 const gchar *name);

Deletes the McsSetting with name `name` from `list`, adjusting the list pointer if necessary.

`list` : | A pointer to an existing McsList.
`name` : | The name of the item to delete.
Returns : | `MCS_SUCCESS` on success.

### mcs_byte_order ()

    gchar       mcs_byte_order                  (void);

Gets the byte ordering for this system.

Returns : | Either `LSBFirst` or `MSBFirst`.

### MCS_PAD()

    #define MCS_PAD(n,m) ((n + m - 1) & (~(m-1)))

`n` : |
`m` : |