Oyranos Color Management System API - Version 0.9.6
Public Member Functions | Data Fields
oyOptions_s Struct Reference

generic Options More...

#include <oyOptions_s.h>

Inheritance diagram for oyOptions_s:
Inheritance graph
Collaboration diagram for oyOptions_s:
Collaboration graph

Public Member Functions

OYAPI oyOptions_s *OYEXPORT oyOptions_New (oyObject_s object)
 allocate a new Options object More...
 
 oyOptions_Copy
 Copy or Reference a Options object. More...
 
OYAPI int OYEXPORT oyOptions_Release (oyOptions_s **options)
 release and possibly deallocate a oyOptions_s object More...
 
OYAPI int OYEXPORT oyOptions_MoveIn (oyOptions_s *list, oyOption_s **obj, int pos)
 add an element to a Options list More...
 
OYAPI int OYEXPORT oyOptions_ReleaseAt (oyOptions_s *list, int pos)
 release a element from a Options list More...
 
OYAPI oyOption_s *OYEXPORT oyOptions_Get (oyOptions_s *list, int pos)
 get a element of a Options list More...
 
OYAPI int OYEXPORT oyOptions_Count (oyOptions_s *list)
 count the elements in a Options list More...
 
OYAPI int OYEXPORT oyOptions_Clear (oyOptions_s *list)
 clear the elements in a Options list More...
 
OYAPI int OYEXPORT oyOptions_Sort (oyOptions_s *list, int32_t *rank_list)
 sort a list according to a rank_list More...
 
 oyOptions_FromBoolean
 boolean operations on two sets of option More...
 
 oyOptions_FromJSON
 deserialise a text file to oyOptions_s data More...
 
oyOptions_soyOptions_FromText (const char *text, uint32_t flags, oyObject_s object)
 deserialise a text file to oyOptions_s data More...
 
int oyOptions_Add (oyOptions_s *options, oyOption_s *option, int pos, oyObject_s object)
 add a element to a Options list More...
 
int oyOptions_Set (oyOptions_s *options, oyOption_s *option, int pos, oyObject_s object)
 set a element in a Options list More...
 
int oyOptions_SetOpts (oyOptions_s *list, oyOptions_s *add)
 set options in a Options list More...
 
int oyOptions_AppendOpts (oyOptions_s *list, oyOptions_s *append)
 Basic reference options from one list into an other. More...
 
int oyOptions_CopyFrom (oyOptions_s **list, oyOptions_s *from, oyBOOLEAN_e type, oyFILTER_REG_e fields, oyObject_s object)
 copy from one option set to an other option set More...
 
int oyOptions_Filter (oyOptions_s **add_list, int32_t *count, uint32_t flags, oyBOOLEAN_e type, const char *registration, oyOptions_s *src_list)
 filter options More...
 
const char * oyOptions_GetText (oyOptions_s *options, oyNAME_e type)
 dump options to text More...
 
int oyOptions_CountType (oyOptions_s *options, const char *registration, oyOBJECT_e type)
 search for options with special attributes More...
 
oyOption_soyOptions_Find (oyOptions_s *options, const char *registration, uint32_t type)
 search for a certain option key More...
 
const char * oyOptions_FindString (oyOptions_s *options, const char *registration, const char *value)
 search for a certain option key and possibly value More...
 
int oyOptions_SetFromText (oyOptions_s **obj, const char *registration, const char *value, uint32_t flags)
 change a value More...
 
int oyOptions_FindInt (oyOptions_s *options, const char *registration, int pos, int32_t *result)
 get a value More...
 
int oyOptions_SetFromInt (oyOptions_s **obj, const char *registration, int32_t value, int pos, uint32_t flags)
 change a value More...
 
int oyOptions_FindDouble (oyOptions_s *options, const char *registration, int pos, double *result)
 get a value More...
 
int oyOptions_SetFromDouble (oyOptions_s **obj, const char *registration, double value, int pos, uint32_t flags)
 change a value More...
 
oyStruct_soyOptions_GetType (oyOptions_s *options, int pos, const char *registration, oyOBJECT_e type)
 select from options with special attribute More...
 
int oyOptions_MoveInStruct (oyOptions_s **obj, const char *registration, oyStruct_s **oy_struct, uint32_t flags)
 change a value More...
 
int oyOptions_SetFromData (oyOptions_s **options, const char *registration, oyPointer ptr, size_t size, uint32_t flags)
 set a data blob or plain pointer More...
 
int oyOptions_FindData (oyOptions_s *options, const char *registration, oyPointer *result, size_t *size, oyAlloc_f allocateFunc)
 get a value More...
 
int oyOptions_SetSource (oyOptions_s *options, oyOPTIONSOURCE_e source)
 set source attribute More...
 
OYAPI int OYEXPORT oyOptions_ObserverAdd (oyOptions_s *object, oyStruct_s *observer, oyStruct_s *user_data, oyObserver_Signal_f signalFunc)
 observe options and its elements More...
 
OYAPI int OYEXPORT oyOptions_ObserversDisable (oyOptions_s *object)
 disable signaling More...
 
OYAPI int OYEXPORT oyOptions_ObserversEnable (oyOptions_s *object)
 disable signaling More...
 
OYAPI int OYEXPORT oyOptions_SetDriverContext (oyOptions_s **options, oyPointer driver_context, const char *driver_context_type, size_t driver_context_size, oyObject_s object)
 set a device option from a given external context More...
 
oyOptions_soyOptions_ForFilter (const char *registration, uint32_t flags, oyObject_s object)
 provide Oyranos behaviour settings More...
 
oyOptions_soyOptions_ForFilter_ (oyFilterCore_s_ *core, oyFilterNode_s_ *node, uint32_t flags, oyObject_s object)
 Provide Oyranos behaviour settings. More...
 
OYAPI int OYEXPORT oyOptions_SaveToDB (oyOptions_s *options, oySCOPE_e scope, const char *registration, char **new_reg, oyAlloc_f allocateFunc)
 store a oyOptions_s in DB More...
 
int oyOptions_DoFilter (oyOptions_s *opts, uint32_t flags, const char *filter_type)
 filter the options More...
 
int oyOptions_Handle (const char *registration, oyOptions_s *options, const char *command, oyOptions_s **result)
 Handle a request by a module. More...
 
- 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 More...
 
const char * oyStruct_GetText (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
 Get a text dump. More...
 
 oyStruct_RegisterStaticMessageFunc
 register a function for verbosity More...
 
 oyStruct_GetInfo
 get a additional string from a object More...
 
const char * oyStructTypeToText (oyOBJECT_e type)
 Objects type to small string. More...
 

Data Fields

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

Detailed Description

generic Options

Options can be any flag or rendering intent and other informations needed to configure a process. The object contains a list of oyOption_s objects.

Note
This class holds a list of objects [list]
Version
Oyranos: x.x.x
Since
YYYY/MM/DD (Oyranos: x.x.x)
Date
YYYY/MM/DD
Examples:
image2pdf.c, image_display.cpp, oyranos_cmm_oJPG.c, tutorial1.c, tutorial_json_options.c, and tutorial_taxi.c.

Member Function Documentation

int oyOptions_Add ( oyOptions_s options,
oyOption_s option,
int  pos,
oyObject_s  object 
)

add a element to a Options list

Function oyOptions_Add

We must not add any already listed option. (oyFILTER_REG_TOP)

Adding a new element without any checks is as simple as following code:

tmp = oyOption_Copy( option, object );
oyOptions_MoveIn( options, &tmp, -1 );
Parameters
[in,out]optionsoptions to manipulate
[in]optionthe option to eventually add
[in]posthe position where to add; use -1 for append
[in]objectthe optional object
Returns
status
  • 0 on success
  • 1 error
  • -2 skipped adding
Version
Oyranos: 0.9.6
Since
2008/11/17 (Oyranos: 0.1.9)
Date
2015/04/29

References oyFILTER_REG_MAX, oyFILTER_REG_TOP, oyFilterRegistrationToText(), oyNAME_PATTERN, oyOption_s::oyOption_Copy(), oyOption_s::oyOption_Release(), oyOPTIONATTRIBUTE_AUTOMATIC, oyOPTIONATTRIBUTE_EDIT, oyOptions_Count(), oyOptions_Find(), oyOptions_Get(), and oyOptions_MoveIn().

Referenced by oyOptions_DoFilter(), and oyOptions_Filter().

int oyOptions_AppendOpts ( oyOptions_s list,
oyOptions_s append 
)

Basic reference options from one list into an other.

Function oyOptions_AppendOpts

See Also
oyOptions_MoveIn
Version
Oyranos:
Since
Date

References oyOptions_Count(), oyOptions_Get(), and oyOptions_MoveIn().

Referenced by oyConfig_s::oyConfig_Count(), oyConfig_s::oyConfig_Get(), oyConfig_s::oyConfig_SaveToDB(), and oyOptions_ForFilter_().

OYAPI int OYEXPORT oyOptions_Clear ( oyOptions_s list)

clear the elements in a Options list

Function oyOptions_Clear

Parameters
[in,out]listthe list
Returns
0 - success; otherwise - error
Version
Oyranos: 0.3.0
Since
2011/02/01 (Oyranos: 0.3.0)
Date
2011/02/01

References oyOBJECT_OPTIONS_S, and oyStructList_s::oyStructList_Clear().

Referenced by oyConfig_s::oyConfig_GetOptions(), oyOptions_DoFilter(), and oyProfiles_s::oyProfiles_DeviceRank().

oyOptions_Copy

Copy or Reference a Options object.

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

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

Referenced by oyConfig_s::oyConfig_SelectDB(), oyConfigs_s::oyConfigs_FromDeviceClass(), oyFilterCore_s::oyFilterCore_NewWith(), oyFilterGraph_s::oyFilterGraph_GetOptions(), oyFilterNode_s::oyFilterNode_GetOptions(), oyFilterNode_s::oyFilterNode_GetTags(), oyImage_s::oyImage_GetTags(), oyImage_s::oyImage_SetCritical(), and oyPixelAccess_s::oyPixelAccess_GetRequestQueue().

int oyOptions_CopyFrom ( oyOptions_s **  list,
oyOptions_s from,
oyBOOLEAN_e  type,
oyFILTER_REG_e  fields,
oyObject_s  object 
)

copy from one option set to an other option set

Function oyOptions_CopyFrom

Parameters
[out]listtarget
[in]fromsource
typeboolean operation before copy
fieldsregistration fields of each option
objectthe optional object
Returns
0 - success; 1 - error; -1 issue
Version
Oyranos: 0.1.10
Since
2009/05/05 (Oyranos: 0.1.10)
Date
2009/10/25
Examples:
image_display.cpp.

References oyBOOLEAN_DIFFERENZ, oyBOOLEAN_INTERSECTION, oyBOOLEAN_SUBSTRACTION, oyBOOLEAN_UNION, oyFilterRegistrationMatch(), oyFilterRegistrationToText(), oyOBJECT_OPTIONS_S, oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), oyOptions_MoveIn(), oyOptions_New(), oyOptions_Release(), oyOptions_SetOpts(), oyStructList_s::oyStructList_Create(), and oyStructList_s::oyStructList_Release().

Referenced by oyFilterPlug_s::oyFilterPlug_ResolveImage(), and oyImage_s::oyImage_ToFile().

OYAPI int OYEXPORT oyOptions_Count ( oyOptions_s list)
int oyOptions_CountType ( oyOptions_s options,
const char *  registration,
oyOBJECT_e  type 
)

search for options with special attributes

Function oyOptions_CountType

Version
Oyranos: 0.1.10
Since
2009/03/04 (Oyranos: 0.1.10)
Date
2009/03/04

References oyFilterRegistrationMatch(), oyOBJECT_OPTIONS_S, oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), and oyVAL_STRUCT.

int oyOptions_DoFilter ( oyOptions_s opts,
uint32_t  flags,
const char *  filter_type 
)

filter the options

Function oyOptions_DoFilter

The returned options are read in from the Elektra settings and if thats not available from the inbuild defaults. The later can explicitely selected with oyOPTIONSOURCE_FILTER passed as flags argument. advanced options can be filtered out by adding oyOPTIONATTRIBUTE_ADVANCED.

Modules should handle the advanced options as well but shall normally not act upon them. The convention to set them zero, keeps them inactive.

On the front end side the CMM cache has to include them, as they will influence the hash sum generation. The question arrises, whether to include these options marked as non visible along the path or require the CMM cache code to check each time for them on cache lookup. The oyOption_s::flags is already in place. So we use it and do inclusion. Front end options can be filtered as they do not affect the CMM cache.

See Also
oyOptions_Add
Parameters
optsthe options
[in]flagsfor inbuild defaults | oyOPTIONSOURCE_FILTER; for options marked as advanced | oyOPTIONATTRIBUTE_ADVANCED; for front end options | oyOPTIONATTRIBUTE_FRONT for already edited options | oyOPTIONATTRIBUTE_EDIT
filter_typethe type level from a registration
Returns
options
Version
Oyranos: 0.9.6
Date
2014/06/30
Since
2008/11/27 (Oyranos: 0.1.9)

References oy_, oyFILTER_REG_TYPE, oyFilterRegistrationToText(), oyNAME_DESCRIPTION, oyNAME_PATTERN, oyOption_s::oyOption_FromDB(), oyOption_s::oyOption_GetRegistration(), oyOption_s::oyOption_GetText(), oyOption_s::oyOption_GetValueString(), oyOption_s::oyOption_Release(), oyOption_s::oyOption_SetFromText(), oyOPTIONATTRIBUTE_ADVANCED, oyOPTIONATTRIBUTE_EDIT, oyOPTIONATTRIBUTE_FRONT, oyOptions_Add(), oyOptions_Clear(), oyOptions_Count(), oyOptions_Find(), oyOptions_Get(), oyOptions_MoveIn(), oyOptions_New(), oyOptions_Release(), oyOPTIONSOURCE_DATA, and oyOPTIONSOURCE_FILTER.

Referenced by oyOptions_ForFilter_().

int oyOptions_Filter ( oyOptions_s **  add_list,
int32_t *  count,
uint32_t  flags,
oyBOOLEAN_e  type,
const char *  registration,
oyOptions_s src_list 
)

filter options

Function oyOptions_Filter

Each option added to the add_list is a cheaply linked one.

See Also
oyOptions_Add
Parameters
[out]add_listthe options list to add to
[out]countthe number of matching options
[in]flagsfor inbuild defaults | oyOPTIONSOURCE_FILTER
[in]typesupport are oyBOOLEAN_INTERSECTION and oyBOOLEAN_DIFFERENZ
[in]registrationa registration which shall be matched
[in]src_listthe options to select from
Returns
0 - success; 1 - error
Version
Oyranos: 0.1.10
Since
2009/05/05 (Oyranos: 0.1.10)
Date
2009/05/05

References oyBOOLEAN_DIFFERENZ, oyBOOLEAN_INTERSECTION, oyBOOLEAN_UNION, oyFilterRegistrationMatch(), oyOBJECT_OPTIONS_S, oyOption_s::oyOption_Release(), oyOptions_Add(), oyOptions_Count(), oyOptions_Get(), oyOptions_New(), oyOPTIONSOURCE_DATA, oyOPTIONSOURCE_FILTER, and oyOPTIONSOURCE_USER.

Referenced by oyFilterNode_s::oyFilterNode_GetOptions(), oyFilterPlug_s::oyFilterPlug_ResolveImage(), and oyPixelAccess_s::oyPixelAccess_Create().

oyOption_s * oyOptions_Find ( oyOptions_s options,
const char *  registration,
uint32_t  type 
)

search for a certain option key

Function oyOptions_Find

This function returns the first found option for a given key. The key is represented by a registrations option level.

Parameters
optionsset of options
registrationregistration or key
typeallowed are:
  • oyNAME_PATTERN for a pattern match, that is what most users prefer
  • oyNAME_REGISTRATION for a exact comparision
Returns
a matching options
Version
Oyranos: 0.1.9
Date
2009/04/13
Since
2008/11/05 (Oyranos: 0.1.9)
Examples:
image_display.cpp.

References oyFilterRegistrationMatch(), oyNAME_PATTERN, oyNAME_REGISTRATION, oyOBJECT_OPTIONS_S, oyOption_s::oyOption_Release(), oyOptions_Count(), and oyOptions_Get().

Referenced by oyConfig_s::oyConfig_Find(), oyConfig_s::oyConfig_Has(), oyDeviceSelectSimiliar(), oyFilterGraph_s::oyFilterGraph_PrepareContexts(), oyFilterNode_s::oyFilterNode_FromOptions(), oyGetPersistentString(), oyOptions_Add(), oyOptions_DoFilter(), oyOptions_FindData(), oyOptions_FindDouble(), oyOptions_FindInt(), oyOptions_FindString(), oyOptions_ForFilter_(), oyOptions_MoveInStruct(), oyOptions_SetFromData(), oyOptions_SetFromDouble(), oyOptions_SetFromInt(), oyOptions_SetFromText(), oyObserver_s::oyStruct_DisableSignalSend(), oyObserver_s::oyStruct_EnableSignalSend(), and oyObserver_s::oyStruct_ObserverSignal().

int oyOptions_FindData ( oyOptions_s options,
const char *  registration,
oyPointer *  result,
size_t *  size,
oyAlloc_f  allocateFunc 
)

get a value

Function oyOptions_FindData

Parameters
optionsthe options list or set to manipulate
registrationthe options registration name, e.g. "org/my_org/openicc/my_app/my_opt" or simply a key, e.g. "my_opt"
[out]resultthe data; With size == zero, the pointer is static and owned somewhere else. With size set, the pointer is owned my
  • the caller.
[out]sizethe data size
[in]allocateFuncuser allocator
Returns
0 - option exists, is of correct type, holds a value; -1 - not found; 1 - error
Version
Oyranos: 0.1.10
Since
2009/11/07 (Oyranos: 0.1.10)
Date
2009/11/07

References oyNAME_PATTERN, oyOBJECT_OPTION_S, oyOBJECT_OPTIONS_S, oyOption_s::oyOption_GetData(), oyOption_s::oyOption_Release(), oyOptions_Find(), oyVAL_STRUCT, and oyOption_s::type_.

int oyOptions_FindDouble ( oyOptions_s options,
const char *  registration,
int  pos,
double *  result 
)

get a value

Function oyOptions_FindDouble

Parameters
optionsthe options list or set to manipulate
registrationthe options registration name, e.g. "org/my_org/openicc/my_app/my_opt" or simple key, e.g. "my_opt"
resultthe double
posthe value position
Returns
0 - option exists, is of correct type, holds a value at the position; -1 - not found; 1 - error
Version
Oyranos: 0.1.10
Since
2009/05/04 (Oyranos: 0.1.10)
Date
2009/09/10
Examples:
image_display.cpp.

References oyNAME_PATTERN, oyOBJECT_OPTION_S, oyOBJECT_OPTIONS_S, oyOption_s::oyOption_GetValueDouble(), oyOption_s::oyOption_Release(), oyOptions_Find(), oyVAL_DOUBLE, and oyVAL_DOUBLE_LIST.

int oyOptions_FindInt ( oyOptions_s options,
const char *  registration,
int  pos,
int32_t *  result 
)

get a value

Function oyOptions_FindInt

Parameters
optionsthe options list or set to manipulate
registrationthe options registration name, e.g. "org/my_org/openicc/my_app/my_opt" or simple key, e.g. "my_opt"
posthe values position in a possible list
resultthe integer
Returns
0 - option exists, is of correct type, holds a value at the position; -1 - not found; 1 - error
Version
Oyranos: 0.1.10
Since
2009/05/04 (Oyranos: 0.1.10)
Date
2009/05/04
Examples:
oyranos_cmm_oJPG.c.

References oyNAME_PATTERN, oyOBJECT_OPTION_S, oyOBJECT_OPTIONS_S, oyOption_s::oyOption_GetValueInt(), oyOption_s::oyOption_Release(), oyOptions_Find(), oyVAL_INT, oyVAL_INT_LIST, and oyOption_s::type_.

Referenced by oyArray2d_s::oyArray2d_SetFocus(), oyDeviceAskProfile2(), oyDeviceFromJSON(), oyDeviceGetProfile(), oyDeviceSetup(), oyFilterPlug_s::oyFilterPlug_ResolveImage(), and oyConfig_s::oyRankMapFromJSON().

const char * oyOptions_FindString ( oyOptions_s options,
const char *  registration,
const char *  value 
)
oyOptions_s * oyOptions_ForFilter ( const char *  registration,
uint32_t  flags,
oyObject_s  object 
)

provide Oyranos behaviour settings

Function oyOptions_ForFilter

The returned options are read in from the Elektra settings and if thats not available from the inbuild defaults. The later can explicitely selected with oyOPTIONSOURCE_FILTER passed as flags argument. The key names map to the registration and XML syntax.

To obtain all advanced front end options from a meta module use:

See Also
OY_SELECT_FILTER OY_SELECT_COMMON oyOPTIONATTRIBUTE_e
Parameters
[in]registrationthe filter registration to search for
[in]flagsfor inbuild defaults | oyOPTIONSOURCE_FILTER; for options marked as advanced | oyOPTIONATTRIBUTE_ADVANCED | OY_SELECT_FILTER | OY_SELECT_COMMON
objectthe optional object
Returns
the options
Version
Oyranos: 0.9.6
Date
2015/01/26
Since
2008/10/08 (Oyranos: 0.1.8)

References oyFilterCore_s::oyFilterCore_Release(), oyOBJECT_CMM_API4_S, and oyOptions_ForFilter_().

oyOptions_s * oyOptions_ForFilter_ ( oyFilterCore_s_ *  core,
oyFilterNode_s_ *  node,
uint32_t  flags,
oyObject_s  object 
)
oyOptions_FromBoolean

boolean operations on two sets of option

See Also
oyOptions_Add
Parameters
[in]set_aoptions set A
[in]set_boptions set B
[in]typethe operation to perform
objectthe optional object
Version
Oyranos: 0.1.8
Since
2008/06/28 (Oyranos: 0.1.8)
Date
2008/06/28

Referenced by oyOptions_ForFilter_().

oyOptions_FromJSON

deserialise a text file to oyOptions_s data

This function is based on oyjl. Arrays are ignored except the index is specified in the xpath with the xformat + ... arguments. The xpath is build from xformat + optional following printf style arguments.

The following code sample comes from tutorial_json_options.c. The "key_path" options is here set to demostrate path substitution:

oyOptions_SetFromText( &options, OY_STD "/key_path",
Then the JSON text is parsed and the second array member of org/free is picked:
json = "{\"org\":{\"free\":[{\"s1key_a\":\"val_a\",\"s1key_b\":\"val_b\"},{\"s2key_c\":\"val_c\",\"s2key_d\":\"val_d\"}],\"key_e\":\"val_e_yyy\",\"key_f\":\"val_f\"}}";
error = oyOptions_FromJSON( json, options, NULL, &result, "org/free/[%d]", 1 );
The result options shall contain net/host/path/s2key_c:val_c and net/host/path/s2key_d:val_d with the path substitution applied and the selected array members taked each into a string option.

Parameters
[in]json_textthe text to process
[in]optionsoptional
  • "underline_key_suffix" will be used as suffix for keys starting with underline '_'
  • "key_path" will be used as suffix to the parsed keys below xpath.
  • "count" will be set to the number of elements in xpath.
[in]objectthe optional object
[out]resultthe result; A existing object will be merged.
[in]xformatthe xpath format string
[in]...variable argument list for xpath
Returns
error
Version
Oyranos: 0.9.6
Since
2016/11/17 (Oyranos: 0.9.6)
Date
2016/11/17
Examples:
tutorial_json_options.c.
oyOptions_s * oyOptions_FromText ( const char *  text,
uint32_t  flags,
oyObject_s  object 
)

deserialise a text file to oyOptions_s data

Function oyOptions_FromText

This function is based on libxml2.

Parameters
[in]textthe text to process
[in]flagsfor future use
objectthe optional object
Returns
the data
Version
Oyranos: 0.1.9
Since
2008/11/17 (Oyranos: 0.1.9)
Date
2008/11/17
Examples:
image_display.cpp.

References oyOptions_New().

Referenced by oyOptions_ForFilter_(), and oyOptions_SetDriverContext().

OYAPI oyOption_s *OYEXPORT oyOptions_Get ( oyOptions_s list,
int  pos 
)
const char * oyOptions_GetText ( oyOptions_s options,
oyNAME_e  type 
)

dump options to text

Function oyOptions_GetText

The type argument should select the following string in return:

  • oyNAME_NAME - a readable XFORMS data model
  • oyNAME_NICK - the hash ID
  • oyNAME_DESCRIPTION - option registration name with key and without value
  • oyNAME_JSON - readable JSON
Todo:
streamline output and group, avoid writing all levels for each key
Parameters
[in,out]optionsthe option
typeoyNAME_NICK is equal to an ID
Returns
the text
Version
Oyranos: 0.9.6
Since
2008/11/25 (Oyranos: 0.1.9)
Date
2016/11/17
Examples:
image_display.cpp, oyranos_cmm_oJPG.c, and tutorial_json_options.c.

References oy_, oyOption_s::oy_, oyNAME_DESCRIPTION, oyNAME_JSON, oyNAME_NAME, oyObject_GetName(), oyObject_SetName(), oyOption_s::oyOption_GetText(), oyOption_s::oyOption_GetValueText(), oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), and oyVAL_STRUCT.

Referenced by oyContextCollectData_(), oyFilterGraph_s::oyFilterGraph_ToText(), oyFilterNode_s::oyFilterNode_Run(), oyImage_s::oyImage_SetCritical(), and oyOption_s::oyOption_GetText().

oyStruct_s * oyOptions_GetType ( oyOptions_s options,
int  pos,
const char *  registration,
oyOBJECT_e  type 
)

select from options with special attribute

Function oyOptions_GetType

Version
Oyranos: 0.1.10
Since
2009/03/04 (Oyranos: 0.1.10)
Date
2009/03/04
Examples:
oyranos_cmm_oJPG.c.

References oyStruct_s::copy, oyStruct_s::oy_, oyFilterRegistrationMatch(), oyOBJECT_OPTIONS_S, oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), oyStruct_s::oyStructTypeToText(), oyVAL_STRUCT, and oyStruct_s::type_.

Referenced by oyImage_s::oyImage_CreateForDisplay().

int oyOptions_Handle ( const char *  registration,
oyOptions_s options,
const char *  command,
oyOptions_s **  result 
)

Handle a request by a module.

Parameters
[in]registrationthe module selector
[in]optionsoptions
[in]commandthe command to handle
[out]resultoptions to the policy module
Returns
0 - indifferent, >= 1 - error, <= -1 - issue,
  • a message should be sent
Version
Oyranos: 0.9.0
Date
2012/10/25
Since
2009/12/11 (Oyranos: 0.1.10)
Examples:
oyranos_cmm_oJPG.c.

References oyCMMapiFilters_s::oyCMMapiFilters_Count(), oyCMMapiFilters_s::oyCMMapiFilters_Get(), oyCMMapiFilters_s::oyCMMapiFilters_Release(), oyFilterRegistrationMatch(), oyOBJECT_CMM_API10_S, and oyOBJECT_OPTIONS_S.

OYAPI int OYEXPORT oyOptions_MoveIn ( oyOptions_s list,
oyOption_s **  obj,
int  pos 
)
int oyOptions_MoveInStruct ( oyOptions_s **  obj,
const char *  registration,
oyStruct_s **  oy_struct,
uint32_t  flags 
)

change a value

Function oyOptions_MoveInStruct

Parameters
objthe options list or set to manipulate
registrationthe options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
oy_structthe Oyranos style object to move in
flagscan be OY_CREATE_NEW for a new option, OY_ADD_ALWAYS, OY_MATCH_KEY
Version
Oyranos: 0.1.10
Since
2009/03/05 (Oyranos: 0.1.10)
Date
2009/03/05

Add a new option if the OY_CREATE_NEW flag is present.

Examples:
image_display.cpp.

References OY_MATCH_KEY, oyGetKeyFromRegistration(), oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOption_s::oyOption_FromRegistration(), oyOption_s::oyOption_MoveInStruct(), oyOption_s::oyOption_Release(), oyOptions_Find(), oyOptions_MoveIn(), oyOptions_New(), and type_.

Referenced by oyImage_s::oyImage_Create().

OYAPI oyOptions_s *OYEXPORT oyOptions_New ( oyObject_s  object)
OYAPI int OYEXPORT oyOptions_ObserverAdd ( oyOptions_s object,
oyStruct_s observer,
oyStruct_s user_data,
oyObserver_Signal_f  signalFunc 
)

observe options and its elements

Function oyOptions_ObserverAdd

Parameters
[in]objectthe options
[in]observerthe in observation intereressted object
[in]user_dataadditional static informations
[in]signalFuncthe signal handler
Returns
0 - fine; 1 - error
Version
Oyranos: 0.1.10
Since
2009/10/28 (Oyranos: 0.1.10)
Date
2009/10/28

References oyObserver_s::oyStruct_ObserverAdd(), and oyStructList_s::oyStructList_ObserverAdd().

Referenced by oyFilterNode_s::oyFilterNode_GetOptions().

OYAPI int OYEXPORT oyOptions_ObserversDisable ( oyOptions_s object)

disable signaling

Function oyOptions_ObserversDisable

Parameters
[in]objectthe options
Returns
0 - fine; 1 - error
Version
Oyranos: 0.1.10
Since
2010/04/07 (Oyranos: 0.1.10)
Date
2010/04/07

References oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), and oyObserver_s::oyStruct_DisableSignalSend().

OYAPI int OYEXPORT oyOptions_ObserversEnable ( oyOptions_s object)

disable signaling

Function oyOptions_ObserversEnable

Parameters
[in]objectthe options
Returns
0 - fine; 1 - error
Version
Oyranos: 0.1.10
Since
2010/04/07 (Oyranos: 0.1.10)
Date
2010/04/07

References oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), and oyObserver_s::oyStruct_EnableSignalSend().

OYAPI int OYEXPORT oyOptions_Release ( oyOptions_s **  options)
OYAPI int OYEXPORT oyOptions_ReleaseAt ( oyOptions_s list,
int  pos 
)

release a element from a Options list

Function oyOptions_ReleaseAt

Parameters
[in,out]listthe list
posposition
Version
Oyranos: 0.1.10
Since
2010/07/05 (Oyranos: 0.1.10)
Date
2010/07/05

References oyOBJECT_OPTIONS_S, oyStructList_s::oyStructList_GetParentObjType(), and oyStructList_s::oyStructList_ReleaseAt().

OYAPI int OYEXPORT oyOptions_SaveToDB ( oyOptions_s options,
oySCOPE_e  scope,
const char *  registration,
char **  new_reg,
oyAlloc_f  allocateFunc 
)

store a oyOptions_s in DB

Function oyOptions_SaveToDB

Parameters
[in]optionsthe options
scopeoySCOPE_USER and oySCOPE_SYS are possible
[in]registrationthe registration
[out]new_regthe new registration; optional
[in]allocthe user allocator for new_reg; optional
Returns
0 - good, 1 >= error
Version
Oyranos: 0.9.6
Date
2015/02/07
Since
2009/02/08 (Oyranos: 0.1.10)

References OY_SLASH, oyFILTER_REG_MAX, oyFilterRegistrationToText(), oyOBJECT_BLOB_S, oyOption_s::oyOption_GetRegistration(), oyOption_s::oyOption_GetValueString(), oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), oySCOPE_USER_SYS, oySetPersistentString(), oyVAL_STRUCT, and oyOption_s::type_.

Referenced by oyConfig_s::oyConfig_SaveToDB().

int oyOptions_Set ( oyOptions_s options,
oyOption_s option,
int  pos,
oyObject_s  object 
)

set a element in a Options list

Function oyOptions_Set

Already listed options are replaced by the new option. A option new to the existing set will be referenced if no object argument is given.

Adding a new element without any checks is as simple as following code:

tmp = oyOption_Copy( option, object );
oyOptions_MoveIn( options, &tmp, -1 );
Version
Oyranos: 0.1.10
Since
2009/10/25 (Oyranos: 0.1.10)
Date
2009/10/25

References oyFilterRegistrationMatchKey(), oyOption_s::oyOption_Copy(), oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), and oyOptions_MoveIn().

Referenced by oyDeviceSetup(), and oyOptions_SetOpts().

OYAPI int OYEXPORT oyOptions_SetDriverContext ( oyOptions_s **  options,
oyPointer  driver_context,
const char *  driver_context_type,
size_t  driver_context_size,
oyObject_s  object 
)

set a device option from a given external context

Function oyOptions_SetDriverContext

The options will be created in case they do not exist. The driver_context_type accepts "xml". The data in driver_context will be converted to a options set following the Oyranos options XML schemes with the help oyOptions_FromText(). Any other pointer will be converted to a oyBlob_s object. The name of that object will come from driver_context_type.

Parameters
[in,out]optionsoptions for the device
[in]driver_contextdriver context
[in]driver_context_type"xml" or something related to the driver
[in]driver_context_sizesize of driver_context
[in]objecta optional object
Returns
1 - error; 0 - success; -1 - otherwise
Version
Oyranos: 0.1.10
Since
2009/05/18 (Oyranos: 0.1.10)
Date
2009/05/18

References oyFilterRegistrationMatch(), oyOBJECT_OPTIONS_S, oyOption_s::oyOption_FromRegistration(), oyOption_s::oyOption_MoveInStruct(), oyOption_s::oyOption_SetFromData(), oyOptions_FromText(), oyOptions_MoveIn(), oyOptions_New(), and oyOptions_Release().

int oyOptions_SetFromData ( oyOptions_s **  options,
const char *  registration,
oyPointer  ptr,
size_t  size,
uint32_t  flags 
)

set a data blob or plain pointer

Function oyOptions_SetFromData

Parameters
optionsthe options list or set to manipulate
registrationthe options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
ptrthe pointer
sizethe pointer size
flagscan be OY_CREATE_NEW for a new option, OY_ADD_ALWAYS, OY_MATCH_KEY
Returns
0 - success; 1 - error
Version
Oyranos: 0.1.10
Since
2009/11/07 (Oyranos: 0.1.10)
Date
2009/11/07

Add a new option if the OY_CREATE_NEW flag is present.

References OY_MATCH_KEY, oyGetKeyFromRegistration(), oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOption_s::oyOption_FromRegistration(), oyOption_s::oyOption_Release(), oyOption_s::oyOption_SetFromData(), oyOptions_Find(), oyOptions_MoveIn(), and oyOptions_New().

int oyOptions_SetFromDouble ( oyOptions_s **  obj,
const char *  registration,
double  value,
int  pos,
uint32_t  flags 
)

change a value

Function oyOptions_SetFromDouble

Parameters
objthe options list or set to manipulate
registrationthe options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
valuethe value to set
posthe position in a value list
flagscan be OY_CREATE_NEW for a new option, OY_ADD_ALWAYS, OY_MATCH_KEY
Returns
0 - success; 1 - error
Version
Oyranos: 0.1.10
Since
2009/05/04 (Oyranos: 0.1.10)
Date
2009/09/10

Add a new option if the OY_CREATE_NEW flag is present.

Examples:
image_display.cpp.

References OY_MATCH_KEY, oyGetKeyFromRegistration(), oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOption_s::oyOption_FromRegistration(), oyOption_s::oyOption_Release(), oyOption_s::oyOption_SetFromDouble(), oyOptions_Find(), oyOptions_MoveIn(), and oyOptions_New().

int oyOptions_SetFromInt ( oyOptions_s **  obj,
const char *  registration,
int32_t  value,
int  pos,
uint32_t  flags 
)

change a value

Function oyOptions_SetFromInt

Parameters
objthe options list or set to manipulate
registrationthe options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
valuethe value to set
posthe position in a value list
flagscan be OY_CREATE_NEW for a new option, OY_MATCH_KEY, OY_ADD_ALWAYS
Returns
0 - success; 1 - error
Version
Oyranos: 0.1.10
Since
2009/05/04 (Oyranos: 0.1.10)
Date
2009/05/04

Add a new option if the OY_CREATE_NEW flag is present.

Examples:
oyranos_cmm_oJPG.c, and tutorial_taxi.c.

References OY_MATCH_KEY, oyGetKeyFromRegistration(), oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOption_s::oyOption_FromRegistration(), oyOption_s::oyOption_Release(), oyOption_s::oyOption_SetFromInt(), oyOptions_Find(), oyOptions_MoveIn(), and oyOptions_New().

Referenced by oyArray2d_s::oyArray2d_Show(), oyDevicesFromTaxiDB(), oyImage_s::oyImage_CreateForDisplay(), and oyImage_s::oyImage_FromFile().

int oyOptions_SetFromText ( oyOptions_s **  obj,
const char *  registration,
const char *  value,
uint32_t  flags 
)

change a value

Function oyOptions_SetFromText

Parameters
objthe options list or set to manipulate
registrationthe options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
valuethe value to set
flagscan be OY_CREATE_NEW for a new option, OY_STRING_LIST, OY_ADD_ALWAYS, OY_MATCH_KEY
Version
Oyranos: 0.3.0
Since
2008/11/27 (Oyranos: 0.1.9)
Date
2011/03/15

Add a new option if the OY_CREATE_NEW flag is present.

Flags are passed on to oyOption_SetFromText, e.g. OY_STRING_LIST.

Examples:
image_display.cpp, oyranos_cmm_oJPG.c, tutorial1.c, tutorial_json_options.c, and tutorial_taxi.c.

References OY_MATCH_KEY, OY_STRING_LIST, oyGetKeyFromRegistration(), oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOption_s::oyOption_FromRegistration(), oyOption_s::oyOption_Release(), oyOption_s::oyOption_SetFromText(), oyOptions_Find(), oyOptions_MoveIn(), oyOptions_New(), and type_.

Referenced by oyConfig_s::oyConfig_AddDBData(), oyConfig_s::oyConfig_SaveToDB(), oyConfigs_s::oyConfigs_FromDB(), oyDeviceSelectSimiliar(), oyDeviceSetup(), oyDevicesFromTaxiDB(), oyImage_s::oyImage_CreateForDisplay(), oyImage_s::oyImage_FromFile(), oyImage_s::oyImage_ToFile(), oyObject_SetName(), and oyProfile_s::oyProfile_GetFileName().

int oyOptions_SetOpts ( oyOptions_s list,
oyOptions_s add 
)

set options in a Options list

Function oyOptions_SetOpts

Already listed options are replaced by the new options.

See Also
oyOptions_Set It will use copying.
Version
Oyranos: 0.1.10
Since
2009/10/25 (Oyranos: 0.1.10)
Date
2009/10/25

References oy_, oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), and oyOptions_Set().

Referenced by oyOptions_CopyFrom().

int oyOptions_SetSource ( oyOptions_s options,
oyOPTIONSOURCE_e  source 
)

set source attribute

Function oyOptions_SetSource

Parameters
optionsthe options list or set to manipulate
sourcethe options new source attribute
Version
Oyranos: 0.1.10
Since
2009/01/27 (Oyranos: 0.1.9)
Date
2009/01/27

References oyOBJECT_OPTIONS_S, oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), and type_.

Referenced by oyConfigs_s::oyConfigs_FromDomain(), and oyProfile_s::oyProfile_GetDevice().

OYAPI int OYEXPORT oyOptions_Sort ( oyOptions_s list,
int32_t *  rank_list 
)

sort a list according to a rank_list

Function oyOptions_Sort

Version
Oyranos: 0.3.0
Since
2011/02/01 (Oyranos: 0.3.0)
Date
2011/02/01

References oyOBJECT_OPTIONS_S, and oyStructList_s::oyStructList_Sort().

Field Documentation

oyStruct_Copy_f oyOptions_s::copy

Copy function.

oyObject_s oyOptions_s::oy_

Oyranos internal object.

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

Referenced by oyImage_s::oyImage_SetCritical(), oyOptions_DoFilter(), oyOptions_GetText(), and oyOptions_SetOpts().

oyStruct_Release_f oyOptions_s::release

Release function.

const oyOBJECT_e oyOptions_s::type_

Type of object.

The struct type tells Oyranos how to interprete hidden fields.

Referenced by oyOptions_MoveInStruct(), oyOptions_SetFromText(), and oyOptions_SetSource().