oyOptions_s Struct Reference
Description: C source code API documentation for the Oyranos project.
Keywords: Oyranos,Color Management,Color Management,ICC,CMS,C,doxygen,API,documentation

| Oyranos Color Management System API - Version 0.9.6

Public Member Functions | Data Fields
oyOptions_s Struct Reference
Miscellaneous » Values Handling

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 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_s * | oyOptions_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_s * | oyOptions_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_s * | oyOptions_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_s * | oyOptions_ForFilter (const char *registration, uint32_t flags, oyObject_s object)
| provide Oyranos behaviour settings More...
oyOptions_s * | oyOptions_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

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

Parameters

  [in,out] | options | 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, oyFilterRegistrationToText(), oyNAME_PATTERN, oyOption_s::oyOption_Copy(), oyOption_s::oyOption_Release(), oyOPTIONATTRIBUTE_AUTOMATIC, oyOPTIONATTRIBUTE_EDIT, oyOptions_Count(), oyOptions_Find(), oyOptions_Get(), and oyOptions_MoveIn().

## ◆ oyOptions_AppendOpts()

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(), and oyConfig_s::oyConfig_SaveToDB().

## ◆ 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, and oyStructList_s::oyStructList_Clear().

Referenced by oyConfig_s::oyConfig_GetOptions().

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

Referenced by oyFilterGraph_s::oyFilterGraph_GetOptions(), oyFilterNode_s::oyFilterNode_GetOptions(), oyFilterNode_s::oyFilterNode_GetTags(), oyImage_s::oyImage_GetTags(), and oyPixelAccess_s::oyPixelAccess_GetRequestQueue().

## ◆ 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, 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 oyImage_s::oyImage_ToFile().

## ◆ 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, and oyStructList_s::oyStructList_Count().

Referenced by oyConfig_s::oyConfig_Count(), oyDeviceGetInfo(), oyDeviceSetProfile(), oyOptions_Add(), oyOptions_AppendOpts(), oyOptions_CopyFrom(), oyOptions_CountType(), oyOptions_GetText(), oyOptions_GetType(), oyOptions_ObserversDisable(), oyOptions_ObserversEnable(), 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 oyFilterRegistrationMatch(), oyOBJECT_OPTIONS_S, oyOption_s::oyOption_Release(), 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)

## ◆ 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

Referenced by oyFilterNode_s::oyFilterNode_GetOptions().

## ◆ 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 | 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)

Referenced by oyConfig_s::oyConfig_Find(), oyConfig_s::oyConfig_Has(), oyFilterGraph_s::oyFilterGraph_PrepareContexts(), oyFilterNode_s::oyFilterNode_FromOptions(), oyOptions_Add(), oyOptions_FindData(), oyOptions_FindDouble(), oyOptions_FindString(), oyObserver_s::oyStruct_DisableSignalSend(), and oyObserver_s::oyStruct_EnableSignalSend().

## ◆ 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 | 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, oyOption_s::oyOption_GetData(), oyOption_s::oyOption_Release(), 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 | 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, oyOption_s::oyOption_GetValueDouble(), oyOption_s::oyOption_Release(), 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 | 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

Examples:
  oyranos_cmm_oJPG.c.

## ◆ 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

Examples:
  oyranos_cmm_oJPG.c, and tutorial_taxi.c.

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

Referenced by oyConfig_s::oyConfig_FindString(), oyDeviceGetInfo(), oyFilterGraph_s::oyFilterGraph_CountNodes(), oyFilterGraph_s::oyFilterGraph_GetNode(), oyObject_GetName(), and oyProfile_s::oyProfile_AddDevice().

## ◆ 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)

## ◆ 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_

Referenced by oyFilterNode_s::oyFilterNode_GetOptions().

## ◆ 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

## ◆ 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",
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_text | the text to process
  [in] | options | 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

Examples:
  tutorial_json_options.c.

## ◆ 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

Referenced by 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, oyOBJECT_OPTIONS_S, and oyStructList_s::oyStructList_GetRefType().

Referenced by oyConfig_s::oyConfig_Get(), oyOptions_Add(), oyOptions_AppendOpts(), oyOptions_CopyFrom(), oyOptions_CountType(), oyOptions_GetText(), oyOptions_GetType(), oyOptions_ObserversDisable(), oyOptions_ObserversEnable(), 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 | 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

Examples:
  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_(), oyFilterNode_s::oyFilterNode_Run(), and oyOption_s::oyOption_GetText().

## ◆ 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

Examples:
  oyranos_cmm_oJPG.c.

References oyStruct_s::copy, oyFilterRegistrationMatch(), oyOBJECT_OPTIONS_S, oyOptions_Count(), oyOptions_Get(), and oyVAL_STRUCT.

Referenced by oyImage_s::oyImage_CreateForDisplay().

## ◆ 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 | 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)

Examples:
  oyranos_cmm_oJPG.c.

References 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

Examples:
  oyranos_cmm_oJPG.c.

References oyOBJECT_OPTION_S, oyOBJECT_OPTIONS_S, oyObserver_s::oyStruct_IsObserved(), oyObserver_s::oyStruct_ObserverAdd(), oyStructList_s::oyStructList_Create(), oyStructList_s::oyStructList_MoveIn(), and oyOption_s::type_.

Referenced by oyOptions_Add(), oyOptions_AppendOpts(), oyOptions_CopyFrom(), oyOptions_Set(), oyOptions_SetDriverContext(), and oyProfile_s::oyProfile_AddDevice().

## ◆ 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.

Examples:
  image_display.cpp.

## ◆ oyOptions_New()

OYAPI oyOptions_s *OYEXPORT oyOptions_New | ( | oyObject_s | object | ) |

allocate a new Options object

Function oyOptions_New

Examples:
  oyranos_cmm_oJPG.c.

References oyOBJECT_OBJECT_S.

Referenced by oyConfig_s::oyConfig_ClearDBData(), oyConfig_s::oyConfig_Count(), oyConfig_s::oyConfig_Get(), oyConfig_s::oyConfig_GetOptions(), oyConfig_s::oyConfig_SaveToDB(), oyDeviceAskProfile2(), oyFilterNode_s::oyFilterNode_GetOptions(), oyFilterNode_s::oyFilterNode_GetTags(), oyOptions_CopyFrom(), and oyOptions_SetDriverContext().

## ◆ 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

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

Referenced by oyFilterNode_s::oyFilterNode_GetOptions().

## ◆ 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 oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), and oyObserver_s::oyStruct_DisableSignalSend().

## ◆ 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 oyOption_s::oyOption_Release(), oyOptions_Count(), oyOptions_Get(), and oyObserver_s::oyStruct_EnableSignalSend().

## ◆ 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 | Options struct object

Examples:
  oyranos_cmm_oJPG.c, tutorial_json_options.c, and tutorial_taxi.c.

References oyOBJECT_OPTIONS_S.

Referenced by oyConfig_s::oyConfig_ClearDBData(), oyConfig_s::oyConfig_Count(), oyConfig_s::oyConfig_Get(), oyGetPersistentStrings(), oyImage_s::oyImage_FromFile(), oyImage_s::oyImage_ToFile(), oyOptions_CopyFrom(), 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, oyStructList_s::oyStructList_GetParentObjType(), and oyStructList_s::oyStructList_ReleaseAt().

## ◆ 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 | 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)

Referenced by oyConfig_s::oyConfig_SaveToDB().

## ◆ 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 oyFilterRegistrationMatchKey(), oyOption_s::oyOption_Copy(), oyOption_s::oyOption_Release(), 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 | 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 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().

## ◆ 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 | 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.

## ◆ 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.

## ◆ 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.

Examples:
  oyranos_cmm_oJPG.c, and tutorial_taxi.c.

Referenced by oyImage_s::oyImage_CreateForDisplay(), and oyImage_s::oyImage_FromFile().

## ◆ 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.

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

Referenced by oyImage_s::oyImage_CreateForDisplay(), oyImage_s::oyImage_FromFile(), oyImage_s::oyImage_ToFile(), and oyObject_SetName().

## ◆ 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_, oyOption_s::oyOption_Release(), 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 | 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, oyOption_s::oyOption_Release(), 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

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