cd-sensor: colord Reference Manual

## cd-sensor cd-sensor — Client object for accessing information about colord sensors |

## Functions

GQuark | cd_sensor_error_quark ()
CdSensor * | cd_sensor_new ()
CdSensor * | cd_sensor_new_with_object_path ()
void | cd_sensor_connect ()
gboolean | cd_sensor_connect_finish ()
void | cd_sensor_lock ()
gboolean | cd_sensor_lock_finish ()
void | cd_sensor_unlock ()
gboolean | cd_sensor_unlock_finish ()
void | cd_sensor_set_options ()
gboolean | cd_sensor_set_options_finish ()
void | cd_sensor_get_sample ()
CdColorXYZ * | cd_sensor_get_sample_finish ()
const gchar * | cd_sensor_get_object_path ()
const gchar * | cd_sensor_get_id ()
gboolean | cd_sensor_get_connected ()
CdSensorKind | cd_sensor_get_kind ()
CdSensorState | cd_sensor_get_state ()
CdSensorCap | cd_sensor_get_mode ()
const gchar * | cd_sensor_get_serial ()
const gchar * | cd_sensor_get_model ()
const gchar * | cd_sensor_get_vendor ()
gboolean | cd_sensor_get_native ()
gboolean | cd_sensor_get_embedded ()
gboolean | cd_sensor_get_locked ()
guint64 | cd_sensor_get_caps ()
gboolean | cd_sensor_has_cap ()
GHashTable * | cd_sensor_get_options ()
const gchar * | cd_sensor_get_option ()
GHashTable * | cd_sensor_get_metadata ()
const gchar * | cd_sensor_get_metadata_item ()
void | cd_sensor_set_object_path ()
gboolean | cd_sensor_equal ()
gchar * | cd_sensor_to_string ()

## Types and Values

#define | CD_SENSOR_ERROR
#define | CD_SENSOR_TYPE_ERROR

## Description

A helper GObject to use for accessing colord sensors, and to be notified when it is changed.

See also: CdClient

## Functions

### cd_sensor_error_quark ()

    GQuark
    cd_sensor_error_quark (void);

#### Returns

An error quark.

Since: 0.1.6

### cd_sensor_new ()

    CdSensor *
    cd_sensor_new (void);

Creates a new CdSensor object.

#### Returns

a new CdSensor object.

Since: 0.1.6

### cd_sensor_new_with_object_path ()

    CdSensor *
    cd_sensor_new_with_object_path (const gchar *object_path);

Creates a new CdSensor object with a known object path.

#### Parameters

object_path | The colord object path. |

#### Returns

a new sensor object.

Since: 0.1.8

### cd_sensor_connect ()

    void
    cd_sensor_connect (CdSensor *sensor,
                       GCancellable *cancellable,
                       GAsyncReadyCallback callback,
                       gpointer user_data);

Connects to the sensor.

#### Parameters

sensor | a CdSensor instance |
cancellable | a GCancellable or `NULL` |
callback | the function to run on completion |
user_data | the data to pass to `callback` |

Since: 0.1.8

### cd_sensor_connect_finish ()

    gboolean
    cd_sensor_connect_finish (CdSensor *sensor,
                              GAsyncResult *res,
                              GError **error);

Gets the result from the asynchronous function.

#### Parameters

sensor | a CdSensor instance |
res | the GAsyncResult |
error | A GError or `NULL` |

#### Returns

`TRUE` if we could connect to to the sensor

Since: 0.1.8

### cd_sensor_lock ()

    void
    cd_sensor_lock (CdSensor *sensor,
                    GCancellable *cancellable,
                    GAsyncReadyCallback callback,
                    gpointer user_data);

Locks the device so we can use it.

#### Parameters

sensor | a CdSensor instance. |
cancellable | a GCancellable, or `NULL` |
callback | the function to run on completion |
user_data | the data to pass to `callback` |

Since: 0.1.8

### cd_sensor_lock_finish ()

    gboolean
    cd_sensor_lock_finish (CdSensor *sensor,
                           GAsyncResult *res,
                           GError **error);

Gets the result from the asynchronous function.

#### Parameters

sensor | a CdSensor instance. |
res | the GAsyncResult |
error | A GError or `NULL` |

#### Returns

success

Since: 0.1.8

### cd_sensor_unlock ()

    void
    cd_sensor_unlock (CdSensor *sensor,
                      GCancellable *cancellable,
                      GAsyncReadyCallback callback,
                      gpointer user_data);

Unlocks the sensor for use by other programs.

#### Parameters

sensor | a CdSensor instance. |
cancellable | a GCancellable, or `NULL` |
callback | the function to run on completion |
user_data | the data to pass to `callback` |

Since: 0.1.8

### cd_sensor_unlock_finish ()

    gboolean
    cd_sensor_unlock_finish (CdSensor *sensor,
                             GAsyncResult *res,
                             GError **error);

Gets the result from the asynchronous function.

#### Parameters

sensor | a CdSensor instance. |
res | the GAsyncResult |
error | A GError or `NULL` |

#### Returns

success

Since: 0.1.8

### cd_sensor_set_options ()

    void
    cd_sensor_set_options (CdSensor *sensor,
                           GHashTable *values,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Sets options on the sensor device.

#### Parameters

sensor | a CdSensor instance. |
values | the options. | [element-type utf8 GVariant]
cancellable | a GCancellable, or `NULL` |
callback | the function to run on completion |
user_data | the data to pass to `callback` |

Since: 0.1.20

### cd_sensor_set_options_finish ()

    gboolean
    cd_sensor_set_options_finish (CdSensor *sensor,
                                  GAsyncResult *res,
                                  GError **error);

Gets the result from the asynchronous function.

#### Parameters

sensor | a CdSensor instance. |
res | the GAsyncResult |
error | A GError or `NULL` |

#### Returns

success

Since: 0.1.20

### cd_sensor_get_sample ()

    void
    cd_sensor_get_sample (CdSensor *sensor,
                          CdSensorCap cap,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Gets a color sample from a sensor

#### Parameters

sensor | a CdSensor instance. |
cap | a CdSensorCap |
cancellable | a GCancellable, or `NULL` |
callback | the function to run on completion |
user_data | the data to pass to `callback` |

Since: 0.1.8

### cd_sensor_get_sample_finish ()

    CdColorXYZ *
    cd_sensor_get_sample_finish (CdSensor *sensor,
                                 GAsyncResult *res,
                                 GError **error);

Gets the result from the asynchronous function.

#### Parameters

sensor | a CdSensor instance. |
res | the GAsyncResult |
error | A GError or `NULL` |

#### Returns

the XYZ reading, or `NULL`

Since: 0.1.8

### cd_sensor_get_object_path ()

    const gchar *
    cd_sensor_get_object_path (CdSensor *sensor);

Gets the object path for the sensor.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

the object path, or `NULL`

Since: 0.1.6

### cd_sensor_get_id ()

    const gchar *
    cd_sensor_get_id (CdSensor *sensor);

Gets the object ID for the sensor.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

the object ID, or `NULL`

Since: 0.1.26

### cd_sensor_get_connected ()

    gboolean
    cd_sensor_get_connected (CdSensor *sensor);

Gets if the sensor has been connected.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

`TRUE` if properties are valid

Since: 0.1.9

### cd_sensor_get_kind ()

    CdSensorKind
    cd_sensor_get_kind (CdSensor *sensor);

Gets the sensor kind.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

A CdSensorKind, e.g. `CD_SENSOR_KIND_HUEY`

Since: 0.1.6

### cd_sensor_get_state ()

    CdSensorState
    cd_sensor_get_state (CdSensor *sensor);

Gets the sensor state.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

A CdSensorState, e.g. `CD_SENSOR_STATE_IDLE`

Since: 0.1.6

### cd_sensor_get_mode ()

    CdSensorCap
    cd_sensor_get_mode (CdSensor *sensor);

Gets the sensor operating mode.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

A CdSensorCap, e.g. `CD_SENSOR_CAP_AMBIENT`

Since: 0.1.6

### cd_sensor_get_serial ()

    const gchar *
    cd_sensor_get_serial (CdSensor *sensor);

Gets the sensor serial number.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

A string, or `NULL` for invalid

Since: 0.1.6

### cd_sensor_get_model ()

    const gchar *
    cd_sensor_get_model (CdSensor *sensor);

Gets the sensor model.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

A string, or `NULL` for invalid

Since: 0.1.6

### cd_sensor_get_vendor ()

    const gchar *
    cd_sensor_get_vendor (CdSensor *sensor);

Gets the sensor vendor.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

A string, or `NULL` for invalid

Since: 0.1.6

### cd_sensor_get_native ()

    gboolean
    cd_sensor_get_native (CdSensor *sensor);

Returns if the sensor has a native driver.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

`TRUE` if VCGT is valid.

Since: 0.1.6

### cd_sensor_get_embedded ()

    gboolean
    cd_sensor_get_embedded (CdSensor *sensor);

Returns if the sensor is embedded into the computer.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

`TRUE` if embedded.

Since: 0.1.26

### cd_sensor_get_locked ()

    gboolean
    cd_sensor_get_locked (CdSensor *sensor);

Returns if the sensor is locked.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

`TRUE` if VCGT is valid.

Since: 0.1.6

### cd_sensor_get_caps ()

    guint64
    cd_sensor_get_caps (CdSensor *sensor);

Returns the sensor metadata.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

The sensor capability bitfield.

Since: 0.1.6

### cd_sensor_has_cap ()

    gboolean
    cd_sensor_has_cap (CdSensor *sensor,
                       CdSensorCap cap);

Returns the sensor metadata for a specific key.

#### Parameters

sensor | a CdSensor instance. |
cap | a specified capability, e.g. `CD_SENSOR_CAP_LCD` |

#### Returns

`TRUE` if the sensor has the specified capability

Since: 0.1.6

### cd_sensor_get_options ()

    GHashTable *
    cd_sensor_get_options (CdSensor *sensor);

Gets any sensor options.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

A refcounted GHashTable of (string, GVariant).

[transfer container][element-type utf8 GVariant]

Since: 0.1.20

### cd_sensor_get_option ()

    const gchar *
    cd_sensor_get_option (CdSensor *sensor,
                          const gchar *key);

Gets a specific sensor option.

#### Parameters

sensor | a CdSensor instance. |
key | a key to search for. |

#### Returns

A const string, or `NULL` of not found.

Since: 0.1.20

### cd_sensor_get_metadata ()

    GHashTable *
    cd_sensor_get_metadata (CdSensor *sensor);

Returns the sensor metadata.

#### Parameters

sensor | a CdSensor instance. |

#### Returns

a GHashTable.

[transfer container][element-type utf8 utf8]

Since: 0.1.28

### cd_sensor_get_metadata_item ()

    const gchar *
    cd_sensor_get_metadata_item (CdSensor *sensor,
                                 const gchar *key);

Returns the sensor metadata for a specific key.

#### Parameters

sensor | a CdSensor instance. |
key | a key for the metadata dictionary |

#### Returns

the metadata value, or `NULL` if not set.

Since: 0.1.28

### cd_sensor_set_object_path ()

    void
    cd_sensor_set_object_path (CdSensor *sensor,
                               const gchar *object_path);

Sets the object path of the sensor.

#### Parameters

sensor | a CdSensor instance. |
object_path | The colord object path. |

Since: 0.1.8

### cd_sensor_equal ()

    gboolean
    cd_sensor_equal (CdSensor *sensor1,
                     CdSensor *sensor2);

Tests two sensors for equality.

#### Parameters

sensor1 | one CdSensor instance. |
sensor2 | another CdSensor instance. |

#### Returns

`TRUE` if the sensors are the same device

Since: 0.1.8

### cd_sensor_to_string ()

    gchar *
    cd_sensor_to_string (CdSensor *sensor);

## Types and Values

### CD_SENSOR_ERROR

    #define CD_SENSOR_ERROR		(cd_sensor_error_quark ())

### CD_SENSOR_TYPE_ERROR

    #define CD_SENSOR_TYPE_ERROR (cd_sensor_error_get_type ())