Color device meta data and profile handling. More...

Collaboration diagram for Device Handling:

Functions
OYAPI int OYEXPORT	oyDevicesGet (const char device_type, const char device_class, oyOptions_s options, oyConfigs_s *devices)
	get all devices matching to a device class and type More...

OYAPI int OYEXPORT	oyDeviceGet (const char device_type, const char device_class, const char device_name, oyOptions_s options, oyConfig_s **device)
	ask a module for device informations or other direct calls More...

OYAPI int OYEXPORT	oyDeviceBackendCall (oyConfig_s device, oyOptions_s options)
	get device answere from options More...

OYAPI int OYEXPORT	oyDeviceSetup (oyConfig_s device, oyOptions_s options)
	activate the device using the stored configuration More...

int	oyDeviceUnset (oyConfig_s *device)
	unset the device profile More...

OYAPI int OYEXPORT	oyDeviceGetInfo (oyConfig_s device, oyNAME_e type, oyOptions_s options, char **info_text, oyAlloc_f allocateFunc)
	get all devices matching to a device class and type More...

OYAPI int OYEXPORT	oyDeviceAskProfile2 (oyConfig_s device, oyOptions_s options, oyProfile_s **profile)
	ask for the device profile More...

int	oyDeviceSetProfile (oyConfig_s device, oySCOPE_e scope, const char profile_name)
	set the device profile More...

OYAPI int OYEXPORT	oyDeviceProfileFromDB (oyConfig_s device, char *profile_name, oyAlloc_f allocateFunc)
	look up a profile of a device from DB More...

OYAPI int OYEXPORT	oyDeviceSelectSimiliar (oyConfig_s pattern, oyConfigs_s heap, uint32_t flags, oyConfigs_s **matched_devices)
	get similiar devices by a pattern from a list More...

OYAPI int OYEXPORT	oyDeviceFromJSON (const char json_text, oyOptions_s options, oyConfig_s **device)
	generate a device from a JSON device calibration More...

OYAPI int OYEXPORT	oyDeviceToJSON (oyConfig_s device, oyOptions_s options, char **json_text, oyAlloc_f allocateFunc)
	get JSON format device calibration text from a device More...

OYAPI int OYEXPORT	oyDeviceCompare (oyConfig_s module_device, oyConfig_s db_pattern, int32_t *rank_value)
	Check for matching to a given pattern. More...

OYAPI int OYEXPORT	oyDevicesFromTaxiDB (oyConfig_s device, oyOptions_s options OY_UNUSED, oyConfigs_s **devices, oyObject_s obj)
	search a calibration state in the taxi DB for a device More...

Detailed Description

Color device meta data and profile handling.

Device Handling inside Oyranos is based on a key/value set, which describes a device and the associated profile. An additional matching set, allows Oyranos to compare different device configurations with a given devices key/value set. If accepted a new device will be added to the proper device key namespace and is permanently stored on disk in a config DB. In case of erasure the key set is removed from the config DB.

The soft matching approach is used in order to compare devices across different ports and computers. The highest match wins and it's profile is assigned. This approach allows to match oven remote profiles like ones from online DB's.

For direct work with the low level key/value matching use oyDeviceFromJSON(), oyRankMapFromJSON() and oyConfig_SetRankMap() API's.

Include the oyranos_devices.h header file to use the interfaces.

Devices are a special form of configurations. Their access is grouped for effective performance. Known devices are queried with oyDevicesGet(). oyConfigDomainList() provides a list of known device modules. A single device can be obtained by oyDeviceGet(). The device_type argument defaults to OY_TYPE_STD and can be omitted for this group. The device_class argument specifies a subgroup, e.g. "monitor".

All other functions return a handle to the device. With this handle it is possible to get informations (oyDeviceGetInfo()), query it's current, possibly remote profile (oyDeviceAskProfile2()) or typical used get a profile with fallbacks including the DB through (oyDeviceGetProfile()), set the profile persistent (oyDeviceSetProfile()) or query the persistent stored profile (oyDeviceProfileFromDB()).

Function Documentation

◆ oyDeviceAskProfile2()

OYAPI int OYEXPORT oyDeviceAskProfile2	(	oyConfig_s *	device,
		oyOptions_s *	options,
		oyProfile_s **	profile
	)

ask for the device profile

Function oyDeviceAskProfile2 Ask for a profile associated with the device. A device capable to hold a profile. Only the held profile will be checked and returned. In case this profile is not found a "icc_profile" of oyVAL_STRUCT should be included.

The device might not be able to hold a profile, then just the DB profile will be returned from here without an issue. For interessted users, the source of the profile keeps transparent, as it can be checked if the device contains a "icc_profile" option which contains a oyProfile_s object.

Parameters

[in]	device	the device
[in]	options	additional options
[out]	profile	the device's ICC profile

Returns: 0 - good, 1 >= error, -1 <= issue(s)

Version: Oyranos: 0.1.10

Since: 2009/02/10 (Oyranos: 0.1.10)

Date: 2009/12/10

◆ oyDeviceBackendCall()

OYAPI int OYEXPORT oyDeviceBackendCall	(	oyConfig_s *	device,
		oyOptions_s *	options
	)

get device answere from options

Function oyDeviceBackendCall

Parameters

[in]	device	the device
[in]	options	options for the device

Returns: error

Version: Oyranos: 0.1.10

Since: 2009/02/02 (Oyranos: 0.1.10)

Date: 2009/08/25

obtain detailed and expensive device informations for a zero options argument through the "properties" command.

1.1 add "properties" call to module arguments

talk to the module

◆ oyDeviceCompare()

OYAPI int OYEXPORT oyDeviceCompare	(	oyConfig_s *	module_device,
		oyConfig_s *	db_pattern,
		int32_t *	rank_value
	)

Check for matching to a given pattern.

Parameters

[in]	module_device	the to be checked configuration from oyConfigs_FromPattern_f; Additional allowed are DB configs.
[in]	db_pattern	the to be compared configuration from elsewhere, e.g. ICC dict tag
[out]	rank_value	the number of matches between config and pattern, -1 means invalid

Returns: 0 - good, >= 1 - error + a message should be sent

Version: Oyranos: 0.9.7

Date: 2017/01/05

Since: 2009/01/26 (Oyranos: 0.1.10)

Examples:: tutorial_taxi.c.

◆ oyDeviceFromJSON()

OYAPI int OYEXPORT oyDeviceFromJSON	(	const char *	json_text,
		oyOptions_s *	options,
		oyConfig_s **	device
	)

generate a device from a JSON device calibration

Function oyDeviceFromJSON

Parameters

[in]	json_text	the device calibration
[in]	options	optional "underline_key_suffix" will be used as suffix for keys starting with underline '_' "pos" integer selects position in array
[out]	device	the device

Returns: error

Version: Oyranos: 0.9.6

Date: 2015/02/10

Since: 2011/08/21 (Oyranos: 0.3.2)

References OY_STD.

◆ oyDeviceGet()

OYAPI int OYEXPORT oyDeviceGet	(	const char *	device_type,
		const char *	device_class,
		const char *	device_name,
		oyOptions_s *	options,
		oyConfig_s **	device
	)

ask a module for device informations or other direct calls

Function oyDeviceGet

oyConfig_s * device = 0;
int error = oyDeviceGet( 0, "monitor", ":0.0", 0, &device );
oyConfig_Release( &device );

// pass empty options to the module to get a usage message
oyOptions_s * options = oyOptions_New( 0 );
oyDeviceGet( OY_TYPE_STD, "monitor", ":0.0", options, 0 );

Parameters

[in]	device_type	the device type, e.g. OY_TYPE_STD, defaults to OY_TYPE_STD (optional)
[in]	device_class	registration oyFILTER_REG_APPLICATION part, e.g. "monitor", mandatory
[in]	device_name	the device name as returned by oyConfigs_FromPattern_f, mandatory, oyFILTER_REG_OPTION
[in]	options	options to pass to the module, for zero the verbose and expensive "properties" call is assumed
[out]	device	the returned device

Returns: error

Version: Oyranos: 0.1.10

Since: 2009/01/28 (Oyranos: 0.1.10)

Date: 2009/02/09

obtain basic device informations

1.1 add "list" call to module arguments

1.1.2 set device filter

get the device
check for success of device detection

Examples:: image2pdf.c.

◆ oyDeviceGetInfo()

OYAPI int OYEXPORT oyDeviceGetInfo	(	oyConfig_s *	device,
		oyNAME_e	type,
		oyOptions_s *	options,
		char **	info_text,
		oyAlloc_f	allocateFunc
	)

get all devices matching to a device class and type

Function oyDeviceGetInfo

// print all properties
int error = oyDeviceGetInfo( device, oyNAME_DESCRIPTION, 0, &text,
                                 malloc );
char * list = text, * tmp = 0, * line = malloc(128);
int even = 1;
    tmp = list;
    while(list && list[0])
    {
      snprintf( line, 128, "%s", list );
      if(strchr( line, '\n' ))
      {
        tmp = strchr( line, '\n' );
        tmp[0] = 0;
      }
      if(even)
        printf( "%s\n", line );
      else
        printf( "  %s\n", line );
      list = strchr( list, '\n' );
      if(list) ++list;
      even = !even;
    }
if(line) free(line);
if(text) free(text);

To obtain a certain single pice of information you do not need oyDeviceGetInfo. See the following example:

char * device_name = ":0.0"; // a typical device
char * text = 0;
oyConfig_s * device = 0;
oyOptions_s * options = 0;
int error = 0;
// tell the module with the "properties" call to add all informations
error = oyOptions_SetFromString( &options, "//" OY_TYPE_STD
                               "/config/command",
                               "properties", OY_CREATE_NEW );
oyDeviceGet( OY_TYPE_STD, "monitor", device_name, options, &device );
text = oyConfig_FindString( device, "manufacturer", 0 );

Parameters

[in]	device	the device
[in]	type	influences the info_text output oyNAME_NAME - a short one line text, oyNAME_NICK - one word, oyNAME_DESCRIPTION - expensive text, even lines contain the property key name, odd lines contain the value, lines are separated by newline '\n'
[in]	options	defaults to command=properties
[out]	info_text	the text
[in]	allocateFunc	the user allocator for info_text

Returns: 0 - good, 1 >= error, -1 <= issue(s)

Version: Oyranos: 0.1.10

Since: 2009/02/02 (Oyranos: 0.1.10)

Date: 2009/03/27

1.2 ask each module

1.2.1 add device_name to the string list

◆ oyDeviceProfileFromDB()

OYAPI int OYEXPORT oyDeviceProfileFromDB	(	oyConfig_s *	device,
		char **	profile_name,
		oyAlloc_f	allocateFunc
	)

look up a profile of a device from DB

Function oyDeviceProfileFromDB The function asks the module for a detailed and possible expensive list of device information and tries to find a matching configuration in the DB. The device informations are the same as for saving to DB.

Parameters

[in]	device	a device
[in]	profile_name	profile's name in DB
[in]	allocateFunc	user allocator

Returns: error

Version: Oyranos: 0.1.10

Since: 2009/01/21 (Oyranos: 0.1.10)

Date: 2009/02/09

◆ oyDeviceSelectSimiliar()

OYAPI int OYEXPORT oyDeviceSelectSimiliar	(	oyConfig_s *	pattern,
		oyConfigs_s *	heap,
		uint32_t	flags,
		oyConfigs_s **	matched_devices
	)

get similiar devices by a pattern from a list

Function oyDeviceSelectSimiliar The function takes a device and tries to find exact matches, which can be considered as belonging to the same device. The comparision can be influenced by the flags. The option "profile_name" is ignored during the comparision.

Parameters

[in]	pattern	Pass a device used as reference. String options of this object are compared to the objects in the heap argument depending on the flags argument. "profile_name" and other options from heap objects are ignored.
[in]	heap	a list of device objects
[in]	flags	- 0 yields exact match 1 compare manufacturer model and serial 2 compare only manufacturer and model 4 compare only device_name
[out]	matched_devices	the devices selected from heap

Returns: error

Version: Oyranos: 0.1.10

Since: 2009/08/27 (Oyranos: 0.1.10)

Date: 2009/08/27

◆ oyDeviceSetProfile()

int oyDeviceSetProfile	(	oyConfig_s *	device,
		oySCOPE_e	scope,
		const char *	profile_name
	)

set the device profile

Function oyDeviceSetProfile The function will lookup the device in the Oyranos device database and stores the given profile there.

To set a new profile und update the device please call the following sequence:

// store new settings in the Oyranos data base
oyDeviceSetProfile( device, profile );
// remove any device entries
oyDeviceUnset( device );
// update the device from the newly added Oyranos data base settings
oyDeviceSetup2( device, options );

Parameters

device	the device
scope	oySCOPE_USER and oySCOPE_SYS are possible
profile_name	the device's ICC profile or zero to unset

Returns: error

Version: Oyranos: 0.9.6

Date: 2015/08/03

Since: 2009/02/07 (Oyranos: 0.1.10)

obtain detailed and expensive device informations

1.1 add "properties" call to module arguments

1.2 call the device module

check for success of device detection
load profile from file name argument

3.1 check for success of profile loading

Now remove all those DB configurations fully matching the selected device.

4.1 get stored DB's configurations

4.1.1 compare if each device key matches to one configuration key

4.1.2 if the 4.1.1 condition is true remove the configuration

save the new configuration with a associated profile
5.1 add the profile simply to the device configuration

5.2 save the configuration to DB (Elektra)

5.3 reload the DB part

Examples:: tutorial_taxi.c.

◆ oyDeviceSetup()

OYAPI int OYEXPORT oyDeviceSetup	(	oyConfig_s *	device,
		oyOptions_s *	options
	)

activate the device using the stored configuration

Function oyDeviceSetup

Deprecated:

Please move on to oyDeviceSetup2() call with extended functionality.

Parameters

[in]	device	the device
[in]	options	additional options, "skip_ask_for_profile == "yes" - skips oyDeviceAskProfile2() call; useful for systems, where no empty profile is possible like CS

Returns: error

Version: Oyranos: 0.9.6

Date: 2015/02/04

Since: 2009/01/30 (Oyranos: 0.1.10)

We ignore a device, which already has its profile setup.

Warn on not found profile.

Examples:: tutorial_taxi.c.

Referenced by oyDeviceSetup2().

◆ oyDevicesFromTaxiDB()

OYAPI int OYEXPORT oyDevicesFromTaxiDB	(	oyConfig_s *	device,
		oyOptions_s *options	OY_UNUSED,
		oyConfigs_s **	devices,
		oyObject_s	obj
	)

search a calibration state in the taxi DB for a device

Function oyDevicesFromTaxiDB oyDevicesFromTaxiDB() needs a device containing the calibration state and gives you a list of found devices in Taxi DB. You can extract the device ID inside the "TAXI_id" string from the returned devices "db" options sets. Typical you want one entry in the profiles list assigned with that device. oyProfile_FromTaxiDB() can be used to download that and oyProfile_Install() helps installing it, while doing some consistency checks.

#include <string.h>
#include <stdio.h>                /* sprintf() */
#include <oyConfig_s.h>
#include <oyOptions_s.h>
#include <oyranos_conversion.h>
#include <oyranos_devices.h>
int main ( int argc OY_UNUSED, char ** argv OY_UNUSED )
{
  // get a device
  oyConfig_s * device = 0;
  oyConfigs_s * ds = 0;
  oyDevicesGet( 0, "monitor", 0, &ds );
  device = oyConfigs_Get( ds, 0 ); oyConfigs_Release( &ds );
  // get all Taxi DB entries for a device
  oyConfigs_s * taxi_devices = 0;
  int error;
  oySCOPE_e scope = oySCOPE_USER;
  error = oyDevicesFromTaxiDB( device, 0, &taxi_devices, 0 );
  // see how many are included
  int n = oyConfigs_Count( taxi_devices ),
      i;
  char * id = calloc( sizeof(char), 1024 );
  for(i = 0; i < n; ++i)
  {
    int32_t rank = 0;
    oyOptions_s * options = NULL;
    oyProfile_s * ip;
    oyConfig_s * taxi_device = oyConfigs_Get( taxi_devices, i );
    error = oyDeviceCompare( device, taxi_device, &rank );
    // get first profile from Taxi DB
    if(i == 0)
    {
      // select the first assigned profile in position zero
      snprintf( id, 1024, "%s/0", oyOptions_FindString(
                                   *oyConfig_GetOptions(taxi_device,"db"),
                                   "TAXI_id", 0 ));
      error = oyOptions_SetFromString( &options,
                                   "//" OY_TYPE_STD "/db/TAXI_id",
                                   id,
                                   OY_CREATE_NEW );
      ip = oyProfile_FromTaxiDB( options, NULL );
      oyOptions_Release( &options );
      if(rank > 0)
      {
        error = oyOptions_SetFromString( &options,
                                       "////device", "1",
                                       OY_CREATE_NEW );
        error = oyProfile_Install( ip, scope, options );
        oyOptions_Release( &options );
        if(!ip)
          printf( "No valid Profile obtained: %s\n", id );
        if(error == oyERROR_DATA_AMBIGUITY)
          printf( "Profile already installed: %s\n", oyProfile_GetText( ip, oyNAME_DESCRIPTION ));
        else if(error == oyERROR_DATA_WRITE)
          printf( "User Path can not be written\n" );
        else if(error == oyCORRUPTED)
          printf( "Profile not useable: %s\n", oyProfile_GetText( ip, oyNAME_DESCRIPTION ) );
        else if(error > 0)
          printf( "%s - %d","Internal Error", error );
        else
        {
          uint32_t icc_profile_flags = 0;
          const char * filename = oyProfile_GetFileName( ip, -1 );
          /* select profiles matching actual capabilities */
          icc_profile_flags = oyICCProfileSelectionFlagsFromOptions( OY_CMM_STD,
                                       "//" OY_TYPE_STD "/icc_color", NULL, 0 );
          printf( "installed -> %s\n", filename );
          // store new settings in the Oyranos data base
          oyDeviceSetProfile( device, oySCOPE_USER, strrchr( filename, OY_SLASH_C ) + 1 );
          // remove any device entries
          oyDeviceUnset( device );
          // update the device from the newly added Oyranos data base settings
          error = oyOptions_SetFromInt( &options,
                                "//" OY_TYPE_STD "/icc_profile_flags",
                                icc_profile_flags, 0, OY_CREATE_NEW );
          error = oyOptions_SetFromString( &options,
                                  "//"OY_TYPE_STD"/config/skip_ask_for_profile", "yes", OY_CREATE_NEW );
          oyDeviceSetup( device, options );
          printf( "assigned -> %s\n", strrchr( filename, OY_SLASH_C ) + 1 );
        }
      }
    }
    if(rank > 0)
    {
      const char * t = oyConfig_FindString(taxi_device, "TAXI_profile_description", 0);
      printf( "rank[%d] %s\n", rank, t?t:"" );
    }
  }
  // release data
  oyConfigs_Release( &taxi_devices );
  return 0;
}

Parameters

[in]	device	the device
[in]	options	not used
[out]	devices	the obtained device calibrations
	obj	the optional object

Returns: 0 - good, >= 1 - error + a message should be sent

Version: Oyranos: 0.9.1

Since: 2011/09/14 (Oyranos: 0.3.2)

Date: 2012/11/15

Examples:: tutorial_taxi.c.

◆ oyDevicesGet()

OYAPI int OYEXPORT oyDevicesGet	(	const char *	device_type,
		const char *	device_class,
		oyOptions_s *	options,
		oyConfigs_s **	devices
	)

get all devices matching to a device class and type

Function oyDevicesGet

// "list" all monitors
oyConfigs_s * monitors = 0;
int error = oyDevicesGet( 0, "monitor", 0, &monitors );
// see how many are included
int n = oyConfigs_Count( monitors );
// release them
oyConfigs_Release( &monitors );

For obtaining expensive "properties" informations at once, add the according option.

// get all monitors the expensive way
oyConfigs_s * monitors = 0;
oyOptions_s * options = oyOptions_New( 0 );
int error = 0;
error = oyOptions_SetFromString( &options, "//" OY_TYPE_STD "/config/command",
                               "properties", OY_CREATE_NEW );
error = oyDevicesGet( 0, "monitor", 0, &monitors );
oyOptions_Release( &options );
// see how many are included
int n = oyConfigs_Count( monitors );
// release them
oyConfigs_Release( &monitors );

Parameters

[in]	device_type	the device type oyFILTER_REG_TYPE, defaults to OY_TYPE_STD (optional)
[in]	device_class	the device class, e.g. "monitor", oyFILTER_REG_APPLICATION
[in]	options	options for the device
[out]	devices	the found devices

Returns: 0 - good, >= 1 - error, <= -1 unknown

Version: Oyranos: 0.1.10

Since: 2009/02/02 (Oyranos: 0.1.10)

Date: 2009/02/02

obtain detailed and expensive device informations

1.1 add "list" call to module arguments

1.2 ask each module

Examples:: tutorial1.c, and tutorial_taxi.c.

◆ oyDeviceToJSON()

OYAPI int OYEXPORT oyDeviceToJSON	(	oyConfig_s *	device,
		oyOptions_s *	options,
		char **	json_text,
		oyAlloc_f	allocateFunc
	)

get JSON format device calibration text from a device

Function oyDeviceToJSON

Parameters

[in]	device	the device
[in]	options	"source" value is used for oyConfig_GetOptions()
[out]	json_text	the device calibration
[in]	allocateFunc	user allocator

Returns: error

Version: Oyranos: 0.3.2

Since: 2011/08/21 (Oyranos: 0.3.2)

Date: 2011/08/21

References oyConfDomain_s::oyConfDomain_FromReg(), oyConfDomain_s::oyConfDomain_GetText(), oyConfDomain_s::oyConfDomain_Release(), oyConfig_s::oyConfig_Count(), oyConfig_s::oyConfig_FindString(), oyConfig_s::oyConfig_Get(), oyConfig_s::oyConfig_GetOptions(), oyNAME_NICK, oyOption_s::oyOption_GetRegistration(), oyOption_s::oyOption_Release(), oyOptions_s::oyOptions_Count(), oyOptions_s::oyOptions_FindString(), and oyOptions_s::oyOptions_Get().

◆ oyDeviceUnset()

int oyDeviceUnset ( oyConfig_s * device )

unset the device profile

Function oyDeviceUnset The function solely calls unset in the module, e.g. unset graphic card luts and server stored profile. So pretty all device/server side informatin should go away.

Parameters

device the device

Returns: error

Version: Oyranos: 0.1.10

Since: 2009/02/12 (Oyranos: 0.1.10)

Date: 2009/02/12

query the full device information

1.1 get device_name

unset the device through the module

2.1 set a general request

2.2 send the query to a module

ping the DB

Examples:: tutorial_taxi.c.

Functions

Detailed Description

Function Documentation

◆ oyDeviceAskProfile2()

◆ oyDeviceBackendCall()

◆ oyDeviceCompare()

◆ oyDeviceFromJSON()

◆ oyDeviceGet()

◆ oyDeviceGetInfo()

◆ oyDeviceProfileFromDB()

◆ oyDeviceSelectSimiliar()

◆ oyDeviceSetProfile()

◆ oyDeviceSetup()

◆ oyDevicesFromTaxiDB()

◆ oyDevicesGet()

◆ oyDeviceToJSON()

◆ oyDeviceUnset()