generic Options More...

#include <oyOptions_s.h>

Inheritance diagram for oyOptions_s:

Collaboration diagram for oyOptions_s:

Public Member Functions
OYAPI oyOptions_s *OYEXPORT	oyOptions_New (oyObject_s object)
	allocate a new Options object
	oyOptions_Copy
	Copy or Reference a Options object.
OYAPI int OYEXPORT	oyOptions_Release (oyOptions_s **options)
	release and possibly deallocate a oyOptions_s object
OYAPI int OYEXPORT	oyOptions_MoveIn (oyOptions_s list, oyOption_s *obj, int pos)
	add an element to a Options list
OYAPI int OYEXPORT	oyOptions_ReleaseAt (oyOptions_s *list, int pos)
	release a element from a Options list
OYAPI oyOption_s *OYEXPORT	oyOptions_Get (oyOptions_s *list, int pos)
	get a element of a Options list
OYAPI int OYEXPORT	oyOptions_Count (oyOptions_s *list)
	count the elements in a Options list
OYAPI int OYEXPORT	oyOptions_Clear (oyOptions_s *list)
	clear the elements in a Options list
OYAPI int OYEXPORT	oyOptions_Sort (oyOptions_s list, int32_t rank_list)
	sort a list according to a rank_list
	oyOptions_FromBoolean
	boolean operations on two sets of option
	oyOptions_FromJSON
	deserialise a text file to oyOptions_s data
oyOptions_s *	oyOptions_FromText (const char *text, uint32_t flags, oyObject_s object)
	deserialise a text file to oyOptions_s data
int	oyOptions_Add (oyOptions_s options, oyOption_s option, int pos, oyObject_s object)
	add a element to a Options list
int	oyOptions_Set (oyOptions_s options, oyOption_s option, int pos, oyObject_s object)
	set a element in a Options list
int	oyOptions_SetOpts (oyOptions_s list, oyOptions_s add)
	set options in a Options list
int	oyOptions_AppendOpts (oyOptions_s list, oyOptions_s append)
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
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
const char *	oyOptions_GetText (oyOptions_s *options, oyNAME_e type)
	dump options to text
int	oyOptions_CountType (oyOptions_s options, const char registration, oyOBJECT_e type)
	search for options with special attributes
oyOption_s *	oyOptions_Find (oyOptions_s options, const char registration, uint32_t type)
	search for a certain option key
const char *	oyOptions_FindString (oyOptions_s options, const char registration, const char *value)
	search for a certain option key and possibly value
int	oyOptions_SetFromText (oyOptions_s *obj, const char registration, const char *value, uint32_t flags)
	change a value
int	oyOptions_FindInt (oyOptions_s options, const char registration, int pos, int32_t *result)
	get a value
int	oyOptions_SetFromInt (oyOptions_s *obj, const char registration, int32_t value, int pos, uint32_t flags)
	change a value
int	oyOptions_FindDouble (oyOptions_s options, const char registration, int pos, double *result)
	get a value
int	oyOptions_SetFromDouble (oyOptions_s *obj, const char registration, double value, int pos, uint32_t flags)
	change a value
oyStruct_s *	oyOptions_GetType (oyOptions_s options, int pos, const char registration, oyOBJECT_e type)
	select from options with special attribute
int	oyOptions_MoveInStruct (oyOptions_s *obj, const char registration, oyStruct_s **oy_struct, uint32_t flags)
	change a value
int	oyOptions_SetFromData (oyOptions_s *options, const char registration, oyPointer ptr, size_t size, uint32_t flags)
	set a data blob or plain pointer
int	oyOptions_FindData (oyOptions_s options, const char registration, oyPointer result, size_t size, oyAlloc_f allocateFunc)
	get a value
int	oyOptions_SetSource (oyOptions_s *options, oyOPTIONSOURCE_e source)
	set source attribute
OYAPI int OYEXPORT	oyOptions_ObserverAdd (oyOptions_s object, oyStruct_s observer, oyStruct_s *user_data, oyObserver_Signal_f signalFunc)
	observe options and its elements
OYAPI int OYEXPORT	oyOptions_ObserversDisable (oyOptions_s *object)
	disable signaling
OYAPI int OYEXPORT	oyOptions_ObserversEnable (oyOptions_s *object)
	disable signaling
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
oyOptions_s *	oyOptions_ForFilter (const char *registration, uint32_t flags, oyObject_s object)
	provide Oyranos behaviour settings
oyOptions_s *	oyOptions_ForFilter_ (oyFilterCore_s_ core, oyFilterNode_s_ node, uint32_t flags, oyObject_s object)
	Provide Oyranos behaviour settings.
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
int	oyOptions_DoFilter (oyOptions_s opts, uint32_t flags, const char filter_type)
	filter the options
int	oyOptions_Handle (const char registration, oyOptions_s options, const char command, oyOptions_s *result)
	Handle a request by a module.
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

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

◆ oyOptions_Add()

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 );

oyOptions_s::oyOptions_MoveIn

OYAPI int OYEXPORT oyOptions_MoveIn(oyOptions_s *list, oyOption_s **obj, int pos)

add an element to a Options list

Definition oyOptions_s.c:120

Parameters

[in,out]	Options API	options to manipulate
[in]	option	the option to eventually add
[in]	pos	the position where to add; use -1 for append
[in]	object	the 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, oyNAME_PATTERN, oyOPTIONATTRIBUTE_AUTOMATIC, oyOPTIONATTRIBUTE_EDIT, oyOptions_Count(), oyOptions_Find(), oyOptions_Get(), and oyOptions_MoveIn().

Referenced by oyOptions_DoFilter(), oyOptions_Filter(), and oyOptions_FromBoolean().

◆ oyOptions_AppendOpts()

int oyOptions_AppendOpts	(	oyOptions_s *	list,
		oyOptions_s *	append )

Function oyOptions_AppendOpts

Basic reference options from one list into an other.

See also: oyOptions_MoveIn

Version: Oyranos:

Since

Date

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

Referenced by oyOptions_ForFilter_().

◆ oyOptions_Clear()

OYAPI int OYEXPORT oyOptions_Clear ( oyOptions_s * list )

clear the elements in a Options list

Function oyOptions_Clear

Parameters

[in,out] list the 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.

Referenced by oyOptions_DoFilter().

◆ oyOptions_Copy()

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]	Options API	Options struct object
	object	NULL - means reference, the optional object triggers a real copy

References oyOBJECT_OPTIONS_S, and oyOptions_Copy().

Referenced by oyOptions_Copy(), and oyOptions_FromBoolean().

◆ oyOptions_CopyFrom()

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]	list	target
[in]	from	source
	type	boolean operation before copy
	fields	registration fields of each option
	object	the 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

References oyBOOLEAN_DIFFERENZ, oyBOOLEAN_INTERSECTION, oyBOOLEAN_SUBSTRACTION, oyBOOLEAN_UNION, oyOBJECT_OPTIONS_S, oyOptions_CopyFrom(), oyOptions_Count(), oyOptions_Get(), oyOptions_MoveIn(), oyOptions_New(), oyOptions_Release(), and oyOptions_SetOpts().

Referenced by oyOptions_CopyFrom().

◆ oyOptions_Count()

OYAPI int OYEXPORT oyOptions_Count ( oyOptions_s * list )

count the elements in a Options list

Function oyOptions_Count

Parameters

[in,out] list the list

Returns: element count

Version: Oyranos: 0.1.10

Since: 2010/07/05 (Oyranos: 0.1.10)

Date: 2010/07/05

References oyOBJECT_OPTIONS_S.

Referenced by oyOptions_Add(), oyOptions_AppendOpts(), oyOptions_CopyFrom(), oyOptions_CountType(), oyOptions_DoFilter(), oyOptions_Filter(), oyOptions_Find(), oyOptions_ForFilter_(), oyOptions_FromBoolean(), oyOptions_GetText(), oyOptions_GetType(), oyOptions_ObserversDisable(), oyOptions_ObserversEnable(), oyOptions_SaveToDB(), oyOptions_Set(), oyOptions_SetOpts(), and oyOptions_SetSource().

◆ oyOptions_CountType()

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 oyOBJECT_OPTIONS_S, oyOptions_Count(), oyOptions_Get(), and oyVAL_STRUCT.

◆ oyOptions_DoFilter()

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

	opts	the options
[in]	flags	for inbuild defaults \| oyOPTIONSOURCE_FILTER; for options marked as advanced \| oyOPTIONATTRIBUTE_ADVANCED; for front end options \| oyOPTIONATTRIBUTE_FRONT for already edited options \| oyOPTIONATTRIBUTE_EDIT
	filter_type	the 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, oyNAME_DESCRIPTION, oyNAME_PATTERN, 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_().

◆ oyOptions_Filter()

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_list	the options list to add to
[out]	count	the number of matching options
[in]	flags	for inbuild defaults \| oyOPTIONSOURCE_FILTER
[in]	type	support are oyBOOLEAN_INTERSECTION and oyBOOLEAN_DIFFERENZ
[in]	registration	a registration which shall be matched
[in]	src_list	the 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, oyOBJECT_OPTIONS_S, oyOptions_Add(), oyOptions_Count(), oyOptions_Get(), oyOptions_New(), oyOPTIONSOURCE_DATA, oyOPTIONSOURCE_FILTER, and oyOPTIONSOURCE_USER.

◆ oyOptions_Find()

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

Options API	set of options
registration	registration or key
type	allowed 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)

References oyNAME_PATTERN, oyNAME_REGISTRATION, oyOBJECT_OPTIONS_S, oyOptions_Count(), oyOptions_Get(), and type_.

Referenced by oyOptions_Add(), oyOptions_DoFilter(), oyOptions_FindData(), oyOptions_FindDouble(), oyOptions_FindInt(), oyOptions_FindString(), oyOptions_ForFilter_(), oyOptions_FromJSON(), oyOptions_MoveInStruct(), oyOptions_SetFromData(), oyOptions_SetFromDouble(), oyOptions_SetFromInt(), and oyOptions_SetFromText().

◆ oyOptions_FindData()

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

get a value

Function oyOptions_FindData

Parameters

	Options API	the options list or set to manipulate
	registration	the options registration name, e.g. "org/my_org/openicc/my_app/my_opt" or simply a key, e.g. "my_opt"
[out]	result	the data; With size == zero, the pointer is static and owned somewhere else. With size set, the pointer is owned my the caller.
[out]	size	the data size
[in]	allocateFunc	user 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, oyOptions_Find(), oyVAL_STRUCT, and oyOption_s::type_.

◆ oyOptions_FindDouble()

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

get a value

Function oyOptions_FindDouble

Parameters

Options API	the options list or set to manipulate
registration	the options registration name, e.g. "org/my_org/openicc/my_app/my_opt" or simple key, e.g. "my_opt"
result	the double
pos	the 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

References oyNAME_PATTERN, oyOBJECT_OPTION_S, oyOBJECT_OPTIONS_S, oyOptions_Find(), oyVAL_DOUBLE, and oyVAL_DOUBLE_LIST.

◆ oyOptions_FindInt()

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

get a value

Function oyOptions_FindInt

Parameters

Options API	the options list or set to manipulate
registration	the options registration name, e.g. "org/my_org/openicc/my_app/my_opt" or simple key, e.g. "my_opt"
pos	the values position in a possible list
result	the 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

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

◆ oyOptions_FindString()

const char * oyOptions_FindString	(	oyOptions_s *	options,
		const char *	registration,
		const char *	value )

search for a certain option key and possibly value

Function oyOptions_FindString

This function returns the first found value for a given key. The key is represented by the oyOption_s::name::nick The returned string is valid along the livetime of the particular option value.

Version: Oyranos: 0.1.9

Since: 2008/10/07 (Oyranos: 0.1.8)

Date: 2009/04/13

References oyNAME_PATTERN, oyOBJECT_OPTION_S, oyOBJECT_OPTIONS_S, oyOptions_Find(), oyVAL_STRING, and oyVAL_STRING_LIST.

Referenced by oyOptions_FromJSON().

◆ oyOptions_ForFilter()

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:

flags = oyOPTIONATTRIBUTE_ADVANCED |
        oyOPTIONATTRIBUTE_FRONT |
        OY_SELECT_COMMON 

See also: OY_SELECT_FILTER OY_SELECT_COMMON oyOPTIONATTRIBUTE_e

Parameters

[in]	registration	the filter registration to search for
[in]	flags	for inbuild defaults \| oyOPTIONSOURCE_FILTER; for options marked as advanced \| oyOPTIONATTRIBUTE_ADVANCED \| OY_SELECT_FILTER \| OY_SELECT_COMMON
	object	the optional object

Returns: the options

Version: Oyranos: 0.9.6

Date: 2015/01/26

Since: 2008/10/08 (Oyranos: 0.1.8)

References oyOBJECT_CMM_API4_S, and oyOptions_ForFilter_().

◆ oyOptions_ForFilter_()

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

Provide Oyranos behaviour settings.

Function oyOptions_ForFilter_

References oyStruct_s::oy_, OY_DEFAULT_CMM_CONTEXT, OY_DEFAULT_CMM_RENDERER, OY_SELECT_COMMON, OY_SELECT_FILTER, oyBOOLEAN_UNION, oyFILTER_REG_MODE_STRIP_IMPLEMENTATION_ATTR, oyFILTER_REG_TYPE, oyNAME_PATTERN, oyOBJECT_CMM_API9_S, oyObject_GetId(), oyOPTIONATTRIBUTE_EDIT, oyOptions_AppendOpts(), oyOptions_Count(), oyOptions_DoFilter(), oyOptions_Find(), oyOptions_FromBoolean(), oyOptions_FromText(), oyOptions_Get(), oyOptions_MoveIn(), oyOptions_New(), oyOptions_Release(), and oyOPTIONSOURCE_FILTER.

Referenced by oyOptions_ForFilter().

◆ oyOptions_FromBoolean()

oyOptions_FromBoolean

boolean operations on two sets of option

See also: oyOptions_Add

Parameters

[in]	set_a	options set A
[in]	set_b	options set B
[in]	type	the operation to perform
	object	the optional object

Version: Oyranos: 0.1.8

Since: 2008/06/28 (Oyranos: 0.1.8)

Date: 2008/06/28

References oyBOOLEAN_DIFFERENZ, oyBOOLEAN_UNION, oyFILTER_REG_OPTION, oyOptions_Add(), oyOptions_Copy(), oyOptions_Count(), oyOptions_FromBoolean(), oyOptions_Get(), and oyOptions_New().

Referenced by oyOptions_ForFilter_(), and oyOptions_FromBoolean().

◆ oyOptions_FromJSON()

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",

OY_STD

#define OY_STD

Definition oyranos_definitions.h:121

oyOptions_s::oyOptions_SetFromText

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

change a value

Definition oyOptions_s.c:1514

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 );

oyOptions_s::oyOptions_FromJSON

oyOptions_FromJSON

deserialise a text file to oyOptions_s data

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_text	the text to process
[in]	Options API	optional "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]	object	the optional object
[out]	result	the result; A existing object will be merged.
[in]	xformat	the 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

References OY_CREATE_NEW, oyNAME_PATTERN, oyOptions_Find(), oyOptions_FindString(), oyOptions_FromJSON(), and oyOptions_SetFromText().

Referenced by oyOptions_FromJSON().

◆ oyOptions_FromText()

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]	text	the text to process
[in]	flags	for future use
	object	the optional object

Returns: the data

Version: Oyranos: 0.1.9

Since: 2008/11/17 (Oyranos: 0.1.9)

Date: 2008/11/17

References oyOptions_New().

Referenced by oyOptions_ForFilter_(), and oyOptions_SetDriverContext().

◆ oyOptions_Get()

OYAPI oyOption_s *OYEXPORT oyOptions_Get	(	oyOptions_s *	list,
		int	pos )

get a element of a Options list

Function oyOptions_Get

Parameters

[in,out]	list	the list
	pos	position

Version: Oyranos: 0.1.10

Since: 2010/07/05 (Oyranos: 0.1.10)

Date: 2010/07/05

References oyOBJECT_OPTION_S, and oyOBJECT_OPTIONS_S.

Referenced by oyOptions_Add(), oyOptions_AppendOpts(), oyOptions_CopyFrom(), oyOptions_CountType(), oyOptions_DoFilter(), oyOptions_Filter(), oyOptions_Find(), oyOptions_ForFilter_(), oyOptions_FromBoolean(), oyOptions_GetText(), oyOptions_GetType(), oyOptions_ObserversDisable(), oyOptions_ObserversEnable(), oyOptions_SaveToDB(), oyOptions_Set(), oyOptions_SetOpts(), and oyOptions_SetSource().

◆ oyOptions_GetText()

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]	Options API	the option
	type	oyNAME_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

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

◆ oyOptions_GetType()

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

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

◆ oyOptions_Handle()

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

Handle a request by a module.

Parameters

[in]	registration	the module selector
[in]	Options API	options
[in]	command	the command to handle
[out]	result	options 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)

References oyFILTER_REG_MODE_STRIP_IMPLEMENTATION_ATTR, oyOBJECT_CMM_API10_S, and oyOBJECT_OPTIONS_S.

◆ oyOptions_MoveIn()

OYAPI int OYEXPORT oyOptions_MoveIn	(	oyOptions_s *	list,
		oyOption_s **	obj,
		int	pos )

add an element to a Options list

Function oyOptions_MoveIn

Parameters

[in]	list	list
[in,out]	obj	list element
	pos	position

Version: Oyranos: 0.1.10

Since: 2010/07/05 (Oyranos: 0.1.10)

Date: 2010/07/05

References oyOBJECT_OPTION_S, oyOBJECT_OPTIONS_S, and oyOption_s::type_.

Referenced by oyOptions_Add(), oyOptions_AppendOpts(), oyOptions_CopyFrom(), oyOptions_DoFilter(), oyOptions_ForFilter_(), oyOptions_MoveInStruct(), oyOptions_Set(), oyOptions_SetDriverContext(), oyOptions_SetFromData(), oyOptions_SetFromDouble(), oyOptions_SetFromInt(), and oyOptions_SetFromText().

◆ oyOptions_MoveInStruct()

int oyOptions_MoveInStruct	(	oyOptions_s **	obj,
		const char *	registration,
		oyStruct_s **	oy_struct,
		uint32_t	flags )

change a value

Function oyOptions_MoveInStruct

Parameters

obj	the options list or set to manipulate
registration	the options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
oy_struct	the Oyranos style object to move in
flags	can 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.

References OY_MATCH_KEY, oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOptions_Find(), oyOptions_MoveIn(), oyOptions_New(), and type_.

◆ oyOptions_New()

OYAPI oyOptions_s *OYEXPORT oyOptions_New ( oyObject_s object )

allocate a new Options object

Function oyOptions_New

References oyOBJECT_OBJECT_S.

Referenced by oyOptions_CopyFrom(), oyOptions_DoFilter(), oyOptions_Filter(), oyOptions_ForFilter_(), oyOptions_FromBoolean(), oyOptions_FromText(), oyOptions_MoveInStruct(), oyOptions_SetDriverContext(), oyOptions_SetFromData(), oyOptions_SetFromDouble(), oyOptions_SetFromInt(), and oyOptions_SetFromText().

◆ oyOptions_ObserverAdd()

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]	object	the options
[in]	observer	the in observation intereressted object
[in]	user_data	additional static informations
[in]	signalFunc	the signal handler

Returns: 0 - fine; 1 - error

Version: Oyranos: 0.1.10

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

Date: 2009/10/28

◆ oyOptions_ObserversDisable()

OYAPI int OYEXPORT oyOptions_ObserversDisable ( oyOptions_s * object )

disable signaling

Function oyOptions_ObserversDisable

Parameters

[in] object the options

Returns: 0 - fine; 1 - error

Version: Oyranos: 0.1.10

Since: 2010/04/07 (Oyranos: 0.1.10)

Date: 2010/04/07

References oyOptions_Count(), and oyOptions_Get().

◆ oyOptions_ObserversEnable()

OYAPI int OYEXPORT oyOptions_ObserversEnable ( oyOptions_s * object )

disable signaling

Function oyOptions_ObserversEnable

Parameters

[in] object the options

Returns: 0 - fine; 1 - error

Version: Oyranos: 0.1.10

Since: 2010/04/07 (Oyranos: 0.1.10)

Date: 2010/04/07

References oyOptions_Count(), and oyOptions_Get().

◆ oyOptions_Release()

OYAPI int OYEXPORT oyOptions_Release ( oyOptions_s ** options )

release and possibly deallocate a oyOptions_s object

Function oyOptions_Release

Parameters

[in,out] Options API Options struct object

References oyOBJECT_OPTIONS_S.

Referenced by oyOptions_CopyFrom(), oyOptions_DoFilter(), oyOptions_ForFilter_(), and oyOptions_SetDriverContext().

◆ oyOptions_ReleaseAt()

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

release a element from a Options list

Function oyOptions_ReleaseAt

Parameters

[in,out]	list	the list
	pos	position

Version: Oyranos: 0.1.10

Since: 2010/07/05 (Oyranos: 0.1.10)

Date: 2010/07/05

References oyOBJECT_OPTIONS_S.

◆ oyOptions_SaveToDB()

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]	Options API	the options
	scope	oySCOPE_USER and oySCOPE_SYS are possible
[in]	registration	the registration
[out]	new_reg	the new registration; optional
[in]	alloc	the 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, oyOBJECT_BLOB_S, oyOptions_Count(), oyOptions_Get(), oySCOPE_USER_SYS, oySetPersistentString(), oyVAL_STRUCT, and oyOption_s::type_.

◆ oyOptions_Set()

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 oyOptions_Count(), oyOptions_Get(), and oyOptions_MoveIn().

Referenced by oyOptions_SetOpts().

◆ oyOptions_SetDriverContext()

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]	Options API	options for the device
[in]	driver_context	driver context
[in]	driver_context_type	"xml" or something related to the driver
[in]	driver_context_size	size of driver_context
[in]	object	a 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 oyOBJECT_OPTIONS_S, oyOptions_FromText(), oyOptions_MoveIn(), oyOptions_New(), and oyOptions_Release().

◆ oyOptions_SetFromData()

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

Options API	the options list or set to manipulate
registration	the options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
ptr	the pointer
size	the pointer size
flags	can 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, oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOptions_Find(), oyOptions_MoveIn(), and oyOptions_New().

◆ oyOptions_SetFromDouble()

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

change a value

Function oyOptions_SetFromDouble

Parameters

obj	the options list or set to manipulate
registration	the options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
value	the value to set
pos	the position in a value list
flags	can 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.

References OY_MATCH_KEY, oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOptions_Find(), oyOptions_MoveIn(), and oyOptions_New().

◆ oyOptions_SetFromInt()

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

change a value

Function oyOptions_SetFromInt

Parameters

obj	the options list or set to manipulate
registration	the options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
value	the value to set
pos	the position in a value list
flags	can 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.

References OY_MATCH_KEY, oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOptions_Find(), oyOptions_MoveIn(), and oyOptions_New().

◆ oyOptions_SetFromText()

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

change a value

Function oyOptions_SetFromText

Parameters

obj	the options list or set to manipulate
registration	the options registration name, e.g. "org/my_org/openicc/my_app/my_opt"
value	the value to set
flags	can 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.

References OY_MATCH_KEY, OY_STRING_LIST, oyNAME_PATTERN, oyOBJECT_OPTIONS_S, oyOptions_Find(), oyOptions_MoveIn(), oyOptions_New(), and type_.

Referenced by oyOptions_FromJSON().

◆ oyOptions_SetOpts()

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_, oyOptions_Count(), oyOptions_Get(), and oyOptions_Set().

Referenced by oyOptions_CopyFrom().

◆ oyOptions_SetSource()

int oyOptions_SetSource	(	oyOptions_s *	options,
		oyOPTIONSOURCE_e	source )

set source attribute

Function oyOptions_SetSource

Parameters

Options API	the options list or set to manipulate
source	the 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, oyOptions_Count(), oyOptions_Get(), and type_.

◆ oyOptions_Sort()

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.

Field Documentation

◆ copy

oyStruct_Copy_f oyOptions_s::copy

Copy function.

◆ oy_

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().

◆ release

oyStruct_Release_f oyOptions_s::release

Release function.

◆ type_

const oyOBJECT_e oyOptions_s::type_

Type of object.

The struct type tells Oyranos how to interprete hidden fields.

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

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ oyOptions_Add()

◆ oyOptions_AppendOpts()

◆ oyOptions_Clear()

◆ oyOptions_Copy()

◆ oyOptions_CopyFrom()

◆ oyOptions_Count()

◆ oyOptions_CountType()

◆ oyOptions_DoFilter()

◆ oyOptions_Filter()

◆ oyOptions_Find()

◆ oyOptions_FindData()

◆ oyOptions_FindDouble()

◆ oyOptions_FindInt()

◆ oyOptions_FindString()

◆ oyOptions_ForFilter()

◆ oyOptions_ForFilter_()

◆ oyOptions_FromBoolean()

◆ oyOptions_FromJSON()

◆ oyOptions_FromText()

◆ oyOptions_Get()

◆ oyOptions_GetText()

◆ oyOptions_GetType()

◆ oyOptions_Handle()

◆ oyOptions_MoveIn()

◆ oyOptions_MoveInStruct()

◆ oyOptions_New()

◆ oyOptions_ObserverAdd()

◆ oyOptions_ObserversDisable()

◆ oyOptions_ObserversEnable()

◆ oyOptions_Release()

◆ oyOptions_ReleaseAt()

◆ oyOptions_SaveToDB()

◆ oyOptions_Set()

◆ oyOptions_SetDriverContext()

◆ oyOptions_SetFromData()

◆ oyOptions_SetFromDouble()

◆ oyOptions_SetFromInt()

◆ oyOptions_SetFromText()

◆ oyOptions_SetOpts()

◆ oyOptions_SetSource()

◆ oyOptions_Sort()

Field Documentation

◆ copy

◆ oy_

◆ release

◆ type_