mcs-common

## mcs-common mcs-common — common MCS utility functions and types |

## Synopsis

                        McsBuffer;
                        McsColor;
                        McsList;
                        McsChannel;
                        McsChannelList;
                        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

### McsBuffer

    typedef struct {
            gchar byte_order;
            size_t len;
            guchar *data;
            guchar *pos;
    } McsBuffer;

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

### McsColor

    typedef struct {
            guint16 red, green, blue, alpha;
    } McsColor;

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.

### McsList

    typedef struct {
            McsSetting *setting;
            McsList *next;
    } McsList;

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.

### McsChannel

    typedef struct {
            gchar *channel_name;
            Atom channel_atom;
            McsList *settings;
            gboolean raw;
            int ref_count;
    } McsChannel;

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.

### McsChannelList

    typedef struct {
            McsChannel *channel;
            McsChannelList *next;
    } McsChannelList;

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.

### McsSetting

    typedef struct {
            gchar *name;
            gchar *channel_name;
            McsType type;

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

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` : |