Oyranos Color Management System API - Version 0.9.6

A group of options for a device. More...

#include <oyConfig_s.h>

Inheritance diagram for oyConfig_s:
Inheritance graph
Collaboration diagram for oyConfig_s:
Collaboration graph

Public Member Functions

OYAPI oyConfig_s *OYEXPORT oyConfig_New (oyObject_s object)
 allocate a new Config object
 oyConfig_Copy
 Copy or Reference a Config object.
OYAPI int OYEXPORT oyConfig_Release (oyConfig_s **config)
 release and possibly deallocate a oyConfig_s object
OYAPI int OYEXPORT oyConfig_AddDBData (oyConfig_s *config, const char *key, const char *value, uint32_t flags)
 add a key value pair to a oyConfig_s::db
OYAPI int OYEXPORT oyConfig_ClearDBData (oyConfig_s *config)
 Remove all additional data from the oyConfig_s::db object cache.
OYAPI int OYEXPORT oyConfig_GetDB (oyConfig_s *device, oyOptions_s *options, int32_t *rank_value)
 search a configuration in the DB for a configuration from module
OYAPI int OYEXPORT oyConfig_SelectDB (oyConfig_s *device, oyConfigs_s *configs, int32_t *rank_value)
 select a db configuration
OYAPI int OYEXPORT oyConfig_SaveToDB (oyConfig_s *config, oySCOPE_e scope)
 Store a oyConfig_s in DB.
OYAPI int OYEXPORT oyConfig_EraseFromDB (oyConfig_s *config, oySCOPE_e scope)
 Remove a oyConfig_s from DB.
int oyConfig_Compare (oyConfig_s *module_device, oyConfig_s *db_pattern, int32_t *rank_value)
 Check for matching to a given pattern.
OYAPI int OYEXPORT oyConfig_DomainRank (oyConfig_s *config)
 Check for being recognised by a given module.
OYAPI const char *OYEXPORT oyConfig_FindString (oyConfig_s *config, const char *key, const char *value)
 Search in data sets for a key/value.
OYAPI int OYEXPORT oyConfig_Has (oyConfig_s *config, const char *key)
 Search in data sets for a key.
OYAPI oyOption_s *OYEXPORT oyConfig_Find (oyConfig_s *config, const char *key)
 Search in data sets for a key.
OYAPI int OYEXPORT oyConfig_Count (oyConfig_s *config)
 Number of all options.
OYAPI oyOption_s *OYEXPORT oyConfig_Get (oyConfig_s *config, int pos)
 Get one option.
OYAPI oyOptions_s **OYEXPORT oyConfig_GetOptions (oyConfig_s *config, const char *source)
 Get options from a source.
OYAPI int OYEXPORT oyConfig_SetRankMap (oyConfig_s *config, const oyRankMap *rank_map)
 Set the ranking table.
OYAPI const oyRankMap *OYEXPORT oyConfig_GetRankMap (oyConfig_s *config)
 Get the ranking table.
OYAPI oyRankMap *OYEXPORT oyRankMapCopy (const oyRankMap *rank_map, oyAlloc_f allocateFunc)
 Copy a rank map.
OYAPI void OYEXPORT oyRankMapRelease (oyRankMap **rank_map, oyDeAlloc_f deAllocateFunc)
 Release a Rank Map.
OYAPI int OYEXPORT oyRankMapAppend (oyRankMap **rank_map, const char *key, int match_value, int none_match_value, int not_found_value, oyAlloc_f allocateFunc, oyDeAlloc_f deAllocateFunc)
 Append a rank map entry.
OYAPI int OYEXPORT oyRankMapFromJSON (const char *json_text, oyOptions_s *options, oyRankMap **rank_map, oyAlloc_f allocateFunc)
 Create a Rank Map.
OYAPI int OYEXPORT oyRankMapToJSON (const oyRankMap *rank_map, oyOptions_s *options, char **json_text, oyAlloc_f allocateFunc)
 Create JSON from a Rank Map.
OYAPI int OYEXPORT oyRankMapList (const char *filter, oyOptions_s *options, char ***rank_map_file_names, oyAlloc_f allocateFunc)
 List installed Rank Map Files.
OYAPI oyConfig_s *OYEXPORT oyConfig_FromRegistration (const char *registration, oyObject_s object)
 New config with registration.
OYAPI int OYEXPORT oyConfig_GetBestMatchFromTaxiDB (oyConfig_s *device, int32_t *rank_value)
 search a profile ID in the Taxi DB for a configuration
OYAPI const char *OYEXPORT oyConfig_GetRegistration (oyConfig_s *config)
 Get the registration string Registration.
OYAPI int OYEXPORT oyConfig_Set (oyConfig_s *config, const char *registration_domain, oyOptions_s *options, oyBlob_s *data)
 Unimplemented!
Public Member Functions inherited from oyStruct_s
const char * oyStruct_GetTextFromModule (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
 get object infos from a module
const char * oyStruct_GetText (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
 Get a text dump.
 oyStruct_RegisterStaticMessageFunc
 register a function for verbosity
 oyStruct_GetInfo
 get a additional string from a object
const char * oyStructTypeToText (oyOBJECT_e type)
 Objects type to small string.

Data Fields

const oyOBJECT_e type_
 Type of object.
oyStruct_Copy_f copy
 Copy function.
oyStruct_Release_f release
 Release function.
oyObject_s oy_
 Oyranos internal object.
Data Fields inherited from oyStruct_s
const oyOBJECT_e type_
 Type of object.
oyStruct_Copy_f copy
 Copy function.
oyStruct_Release_f release
 Release function.
oyObject_s oy_
 Oyranos internal object.

Detailed Description

A group of options for a device.

Version
Oyranos: 0.1.10
Since
2009/01/15 (Oyranos: 0.1.10)
Date
2009/01/15
Examples
image2pdf.c, tutorial1.c, and tutorial_taxi.c.

Member Function Documentation

◆ oyConfig_AddDBData()

OYAPI int OYEXPORT oyConfig_AddDBData ( oyConfig_s * config,
const char * key,
const char * value,
uint32_t flags )

add a key value pair to a oyConfig_s::db

Function oyConfig_AddDBData

This functions handles canonical user side settings. The keys added with this function can later be stored in the DB. A call to oyConfig_GetDB() or oyConfig_ClearDBData() overwrite the added entries.
Modules should add informations to oyConfig_s::data.

Parameters
[in]configthe configuration
[in]keya key name, e.g. "my_key"
[in]valuea value, e.g. "my_value"
[in]flagssee oyOptions_s::oyOptions_SetFromText(.., flags,..)
Returns
0 - good, 1 >= error
Version
Oyranos: 0.1.10
Since
2009/01/21 (Oyranos: 0.1.10)
Date
2009/02/08

We provide basically a wrapper for oyOptions_SetFromText().

References OY_SLASH, OY_SLASH_C, and oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_ClearDBData()

OYAPI int OYEXPORT oyConfig_ClearDBData ( oyConfig_s * config)

Remove all additional data from the oyConfig_s::db object cache.

Function oyConfig_ClearDBData

Clear the local DB cache. The function will be called as well from oyConfig_GetDB().

Parameters
[in]configthe configuration
Returns
0 - good, 1 >= error
Version
Oyranos: 0.1.10
Since
2009/02/08 (Oyranos: 0.1.10)
Date
2009/02/08

References oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_Compare()

int oyConfig_Compare ( oyConfig_s * module_device,
oyConfig_s * db_pattern,
int32_t * rank_value )

Check for matching to a given pattern.

Function oyConfig_Compare

Parameters
[in]module_devicethe to be checked configuration from oyConfigs_FromPattern_f; Additional allowed are DB configs.
[in]db_patternthe to be compared configuration from elsewhere, e.g. ICC dict tag
[out]rank_valuethe number of matches between config and pattern, -1 means invalid
Returns
0 - good, >= 1 - error + a message should be sent
Version
Oyranos: 0.9.6
Date
2015/08/03
Since
2009/01/26 (Oyranos: 0.1.10)

Option name is equal and and value matches : increase rank value

we need a comparision mechanism here. The pattern value should be expandable to several values. Do we need more than the ICC dict style syntax here?

References oy_debug, oyFILTER_REG_MAX, and oyOBJECT_CONFIG_S.

Referenced by oyConfig_SelectDB(), and oyConfig_Set().

◆ oyConfig_Copy()

oyConfig_Copy

Copy or Reference a Config object.

The function is for copying and for referencing. The reference is the most often used way, which saves resourcs and time.

Parameters
[in]configConfig struct object
objectNULL - means reference, the optional object triggers a real copy

References oyConfig_Copy(), and oyOBJECT_CONFIG_S.

Referenced by oyConfig_Copy(), and oyConfig_SelectDB().

◆ oyConfig_Count()

OYAPI int OYEXPORT oyConfig_Count ( oyConfig_s * config)

Number of all options.

Function oyConfig_Count

Parameters
[in]configthe configuration
Returns
the options count
Version
Oyranos: 0.1.10
Since
2009/02/08 (Oyranos: 0.1.10)
Date
2009/02/08

References oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_DomainRank()

OYAPI int OYEXPORT oyConfig_DomainRank ( oyConfig_s * config)

Check for being recognised by a given module.

Function oyConfig_DomainRank

Parameters
[in]configthe configuration to be checked wether or not the module can make sense of it and support the data
Returns
0 - indifferent, <= -1 - no fit
Version
Oyranos: 0.1.10
Since
2009/01/26 (Oyranos: 0.1.10)
Date
2009/01/26

Ask the module if it wants later on to accept this configuration.

References oyOBJECT_CMM_API8_S, and oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_EraseFromDB()

OYAPI int OYEXPORT oyConfig_EraseFromDB ( oyConfig_s * config,
oySCOPE_e scope )

Remove a oyConfig_s from DB.

Function oyConfig_EraseFromDB

Parameters
[in]configthe configuration
scopeoySCOPE_USER and oySCOPE_SYS are possible
Returns
0 - good, 1 >= error
Version
Oyranos: 0.9.6
Date
2015/03/07
Since
2009/01/27 (Oyranos: 0.1.10)

If a key has one slash more than 4. Cut the last slash off.

Cut off any attributes to the config::registration.

References OY_SLASH_C, and oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_Find()

OYAPI oyOption_s *OYEXPORT oyConfig_Find ( oyConfig_s * config,
const char * key )

Search in data sets for a key.

Function oyConfig_Find

Parameters
[in]configthe configuration to be checked wether or not the module can make sense of it and support the data
[in]keythe key name
Returns
the found value
Version
Oyranos: 0.1.10
Since
2009/02/08 (Oyranos: 0.1.10)
Date
2009/02/08

References oyNAME_PATTERN, and oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_FindString()

OYAPI const char *OYEXPORT oyConfig_FindString ( oyConfig_s * config,
const char * key,
const char * value )

Search in data sets for a key/value.

Function oyConfig_FindString

Parameters
[in]configthe configuration to be checked wether or not the module can make sense of it and support the data
[in]keythe key name
[in]valuethe optional value
Returns
the found value
Version
Oyranos: 0.1.10
Since
2009/02/08 (Oyranos: 0.1.10)
Date
2009/02/08

References oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_FromRegistration()

OYAPI oyConfig_s *OYEXPORT oyConfig_FromRegistration ( const char * registration,
oyObject_s object )

New config with registration.

Function oyConfig_FromRegistration

Parameters
registrationno or full qualified registration
objectthe optional object
Returns
the config
Version
Oyranos: 0.1.11
Since
2010/08/09 (Oyranos: 0.1.11)
Date
2010/08/09

References oyConfig_New().

Referenced by oyConfig_Set().

◆ oyConfig_Get()

OYAPI oyOption_s *OYEXPORT oyConfig_Get ( oyConfig_s * config,
int pos )

Get one option.

Function oyConfig_Get

Parameters
[in]configthe configuration
[in]posoption position
Returns
the selected option
Version
Oyranos: 0.1.10
Since
2009/02/08 (Oyranos: 0.1.10)
Date
2009/02/08

References oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_GetBestMatchFromTaxiDB()

OYAPI int OYEXPORT oyConfig_GetBestMatchFromTaxiDB ( oyConfig_s * device,
int32_t * rank_value )

search a profile ID in the Taxi DB for a configuration

Function oyConfig_GetBestMatchFromTaxiDB

Parameters
[in]devicethe to be checked configuration from oyConfigs_FromPattern_f
[out]rank_valuethe number of matches between config and pattern, -1 means invalid
Returns
0 - good, >= 1 - error + a message should be sent
Version
Oyranos: 0.3.2
Since
2009/01/26 (Oyranos: 0.3.2)
Date
2011/09/14

References oyConfig_SelectDB(), oyDevicesFromTaxiDB(), and oyOBJECT_CONFIG_S.

◆ oyConfig_GetDB()

OYAPI int OYEXPORT oyConfig_GetDB ( oyConfig_s * device,
oyOptions_s * options,
int32_t * rank_value )

search a configuration in the DB for a configuration from module

Function oyConfig_GetDB

Parameters
[in]devicethe to be checked configuration from oyConfigs_FromPattern_f
[in]Options APIsupported is "module" containing a registration string to select a module, see as well oyConfigs_FromDB()
[out]rank_valuethe number of matches between config and pattern, -1 means invalid
Returns
0 - good, >= 1 - error + a message should be sent
Version
Oyranos: 0.3.0
Since
2009/01/26 (Oyranos: 0.1.10)
Date
2012/09/15

References oyConfig_SelectDB(), and oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_GetOptions()

OYAPI oyOptions_s **OYEXPORT oyConfig_GetOptions ( oyConfig_s * config,
const char * source )

Get options from a source.

Function oyConfig_GetOptions

This API allows low level operations on a Config object. Do not release the returned Options without replacement inside the Config object.

A Config object has three kind of options.

The data base "db" properties are for persistent storage in a DB, e.g. "org/freedesktop/imaging/config.monitor.xorg/1/manufacturer=EIZO"

The "backend_core" options are the module core properties, the ones to identify the device and store in DB. They must be filled by the module. e.g. "org/freedesktop/imaging/config.monitor.xorg/manufacturer=EIZO"

The "data" properties are additional options without identification purpose and not intended for DB storage, e.g. "org/freedesktop/imaging/config.monitor.xorg/edid=oyBlob_s*"

Parameters
[in]configthe configuration
[in]sourceuse of the options,
  • "db" for persistent options
  • "backend_core" for module options
  • "data" for module options without identification purpose
Returns
the selected options, in the domain of the config
Version
Oyranos: 0.5.0
Date
2012/10/03
Since
2012/10/03 (Oyranos: 0.5.0)

References oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_GetRankMap()

OYAPI const oyRankMap *OYEXPORT oyConfig_GetRankMap ( oyConfig_s * config)

Get the ranking table.

Function oyConfig_GetRankMap

Parameters
[in]configthe configuration
Returns
rank_map the rank map
Version
Oyranos: 0.5.0
Date
2012/10/03
Since
2012/10/03 (Oyranos: 0.5.0)

References oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_GetRegistration()

OYAPI const char *OYEXPORT oyConfig_GetRegistration ( oyConfig_s * config)

Get the registration string Registration.

Function oyConfig_GetRegistration

Parameters
[in]configthe config
Returns
the registration string
Version
Oyranos: 0.5.0
Date
2012/09/19
Since
2012/09/19 (Oyranos: 0.5.0)

References oyOBJECT_CONFIG_S.

Referenced by oyConfig_SaveToDB(), and oyConfig_Set().

◆ oyConfig_Has()

OYAPI int OYEXPORT oyConfig_Has ( oyConfig_s * config,
const char * key )

Search in data sets for a key.

Function oyConfig_Has

Parameters
[in]configthe configuration to be checked wether or not the module can make sense of it and support the data
[in]keythe key name
Returns
0 - not found; 1 - key found
Version
Oyranos: 0.1.10
Since
2009/12/10 (Oyranos: 0.1.10)
Date
2009/12/10

References oyNAME_PATTERN, and oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_New()

OYAPI oyConfig_s *OYEXPORT oyConfig_New ( oyObject_s object)

allocate a new Config object

Function oyConfig_New

References oyOBJECT_OBJECT_S.

Referenced by oyConfig_FromRegistration().

◆ oyConfig_Release()

OYAPI int OYEXPORT oyConfig_Release ( oyConfig_s ** config)

release and possibly deallocate a oyConfig_s object

Function oyConfig_Release

Parameters
[in,out]configConfig struct object

References oyOBJECT_CONFIG_S.

Referenced by oyConfig_SelectDB().

◆ oyConfig_SaveToDB()

OYAPI int OYEXPORT oyConfig_SaveToDB ( oyConfig_s * config,
oySCOPE_e scope )

Store a oyConfig_s in DB.

Function oyConfig_SaveToDB

The new key set name is stored inside the key "key_set_name".

Parameters
[in]configthe configuration
scopeoySCOPE_USER and oySCOPE_SYS are possible
Returns
0 - good, 1 >= error
Version
Oyranos: 0.1.10
Since
2009/01/21 (Oyranos: 0.1.10)
Date
2011/01/29

References OY_CREATE_NEW, oyConfig_GetRegistration(), and oyOBJECT_CONFIG_S.

Referenced by oyConfig_Set().

◆ oyConfig_SelectDB()

OYAPI int OYEXPORT oyConfig_SelectDB ( oyConfig_s * device,
oyConfigs_s * configs,
int32_t * rank_value )

select a db configuration

Function oyConfig_SelectDB

This function is useful to fill the best matching config into the db options set.

Parameters
[in,out]devicethe to be checked configuration from oyConfigs_FromPattern_f
[in]configsthe possible configs to select the best db match from
[out]rank_valuethe number of matches between config and pattern, -1 means invalid
Returns
0 - good, >= 1 - error + a message should be sent
Version
Oyranos: 0.9.6
Date
2015/02/15
Since
2009/01/26 (Oyranos: 0.3.2)
  1. iterate over all configs
  1. oyConfig_Compare() with the provided device
  1. store the biggest rank_value
  1. copy the config::db from configs with the biggest rank_value into the device::db

References oyConfig_Compare(), oyConfig_Copy(), oyConfig_Release(), and oyOBJECT_CONFIG_S.

Referenced by oyConfig_GetBestMatchFromTaxiDB(), oyConfig_GetDB(), and oyConfig_Set().

◆ oyConfig_Set()

◆ oyConfig_SetRankMap()

OYAPI int OYEXPORT oyConfig_SetRankMap ( oyConfig_s * config,
const oyRankMap * rank_map )

Set the ranking table.

Function oyConfig_SetRankMap

Parameters
[in,out]configthe configuration
[in]rank_mapthe new rank map
Returns
error
Version
Oyranos: 0.5.0
Date
2012/10/03
Since
2012/10/03 (Oyranos: 0.5.0)

References oyOBJECT_CONFIG_S, oyRankMapCopy(), and oyRankMapRelease().

Referenced by oyConfig_Set().

◆ oyRankMapAppend()

OYAPI int OYEXPORT oyRankMapAppend ( oyRankMap ** rank_map,
const char * key,
int match_value,
int none_match_value,
int not_found_value,
oyAlloc_f allocateFunc,
oyDeAlloc_f deAllocateFunc )

Append a rank map entry.

Function oyRankMapAppend

A helper function to continually construct rank maps.

Parameters
[in,out]rank_mapa pointer to a data structure, The pointed to structure can be NULL.
[in]keythe key to apply ranking to
[in]match_valuea found and matched value
[in]none_match_valuea found and not matched value
[in]not_found_valuea not found value
[in]allocateFuncthe memory allocation function, optional
[in]deAllocateFuncthe memory release function, optional
Version
Oyranos: 0.9.5
Date
2013/02/22
Since
2013/02/22 (Oyranos: 0.9.5)

References oyRankMapRelease().

Referenced by oyConfig_Set().

◆ oyRankMapCopy()

OYAPI oyRankMap *OYEXPORT oyRankMapCopy ( const oyRankMap * rank_map,
oyAlloc_f allocateFunc )

Copy a rank map.

Function oyRankMapCopy

Version
Oyranos: 0.1.10
Since
2009/01/27 (Oyranos: 0.1.10)
Date
2009/01/27

Referenced by oyConfig_Set(), and oyConfig_SetRankMap().

◆ oyRankMapFromJSON()

OYAPI int OYEXPORT oyRankMapFromJSON ( const char * json_text,
oyOptions_s * options,
oyRankMap ** rank_map,
oyAlloc_f allocateFunc )

Create a Rank Map.

Function oyRankMapFromJSON

Parameters
[in]json_textthe rank map definition
[in]Options APIoptional
  • "pos" integer selects position in array
[out]rank_mapthe result
[in]allocateFuncthe memory allocate function
Returns
0 - good, >= 1 - error + a message should be sent, < 0 - an issue
Version
Oyranos: 0.9.5
Date
2013/02/13
Since
2013/02/13 (Oyranos: 0.9.5)

Referenced by oyConfig_Set().

◆ oyRankMapList()

OYAPI int OYEXPORT oyRankMapList ( const char * filter,
oyOptions_s * options,
char *** rank_map_file_names,
oyAlloc_f allocateFunc )

List installed Rank Map Files.

Function oyRankMapList

Load the file content with oyRankMapFromJSON().

Parameters
[in]filtera string to prefilter file names; optional
[in]Options API- "path" - show paths instead of files
[out]rank_map_file_nameszero terminated list of rank map JSON files
[in]allocateFuncthe memory allocate function
Returns
0 - good, >= 1 - error + a message should be sent, < 0 - an issue
Version
Oyranos: 0.9.6
Date
2015/08/04
Since
2015/08/04 (Oyranos: 0.9.6)

References oy_debug, oySCOPE_USER_SYS, and oyYES.

Referenced by oyConfig_Set().

◆ oyRankMapRelease()

OYAPI void OYEXPORT oyRankMapRelease ( oyRankMap ** rank_map,
oyDeAlloc_f deAllocateFunc )

Release a Rank Map.

Function oyRankMapRelease

Parameters
[in,out]rank_mapthe rank map
[in]deAllocateFuncthe memory release function
Returns
error
Version
Oyranos: 0.5.0
Date
2012/10/03
Since
2012/10/03 (Oyranos: 0.5.0)

Referenced by oyConfig_Set(), oyConfig_SetRankMap(), and oyRankMapAppend().

◆ oyRankMapToJSON()

OYAPI int OYEXPORT oyRankMapToJSON ( const oyRankMap * rank_map,
oyOptions_s * options,
char ** json_text,
oyAlloc_f allocateFunc )

Create JSON from a Rank Map.

Function oyRankMapToJSON

Parameters
[in]rank_mapthe rank map
[in]Options APIoptional
  • "pos" integer selects position in array
  • "device_class" will be placed into the JSON
[out]json_textthe result
[in]allocateFuncthe memory allocate function
Returns
0 - good, >= 1 - error + a message should be sent, < 0 - an issue
Version
Oyranos: 0.9.5
Date
2013/02/13
Since
2013/02/13 (Oyranos: 0.9.5)

Referenced by oyConfig_Set().

Field Documentation

◆ copy

oyStruct_Copy_f oyConfig_s::copy

Copy function.

◆ oy_

oyObject_s oyConfig_s::oy_

Oyranos internal object.

Features name and hash. Do not change during object life time.

Referenced by oyConfigs_s::oyConfigs_FromDB(), and oyConfigs_s::oyConfigs_FromDeviceClass().

◆ release

oyStruct_Release_f oyConfig_s::release

Release function.

◆ type_

const oyOBJECT_e oyConfig_s::type_

Type of object.

The struct type tells Oyranos how to interprete hidden fields.

Referenced by oyConfigs_s::oyConfigs_MoveIn().