Oyranos Colour Management System API
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Device Protocol v1.0

Oyranos core <-> device module protocol

Copyright: Kai-Uwe Behrmann, Yiannis Belias @ 2009

Implementation Overview

Oyranos implements devices as oyConfig_s objects.

A 'oyConfig_s' object holds a set of options comming from a device backend and possibly from the Oyranos DataBase (Oyranos DB).

Options which are relevant for inclusion into the Oyranos DB must be build of text strings. These are the oyConfig_s::backend_core options.

The device options represent both device attributes and driver settings in one object.

The device backend is implemented in Oyranos with the oyCMMapi8_s structure. This structure must be included in a module and be pointed to from a oyCMMInfo_s structure like all modules.

Tables

Options marked with "in:" are passed through a oyOptions_s argument to the module. Outgoing options are passed through the device(s) created by the modules and are assigned as follows:

[c] - oyConfig_s::backend_core - identification stuff as strings

[d] - oyConfig_s::data - additional data

[b] - oyConfig_s::db - only for Oyranos core and thus tabu for modules

Required options are marked with a [r].

The "device_name" option shall only be considered in oyConfig_s::oyConfigs_FromPattern. In oyConfig_s::oyConfigs_Modify the oyConfig_s's devices should have already that property in their backend_core part.

"list" call
Property Modules Informations Data format
"command"="list" oyX1, SANE, CUPS, oyRE in[r]: call for detected device(s) in: string
"device_name" oyX1, SANE, CUPS
oyRE
device ID in: select a single device; out[r]: device ID
any meaning for oyRE?
in(oyConfigs_FromPattern)/out[c]: string
"oyNAME_NAME" oyX1, SANE, CUPS, oyRE in: call for lightweight informations
out: short UI description
in/out[d]: string
"icc_profile" oyX1, CUPS out: the ICC profile accessible through the device driver in: string; out[d]: oyProfile_s or
a empty "icc_profile" option of oyVAL_STRUCT, if ICC profiles are supported by the device but in the actual search not found.
"display_name" oyX1 in: select a X11 display and get all connected devices; "device_name" has priority in(oyConfigs_FromPattern): string
"device_rectangle" oyX1 out[r]: the device rectangle in pixels in: string
out[d]: oyRectangle_s
"supported_devices" oyRE out: one manufacturer in the first line, remaining lines each for one model in: string
out[d]: strings
"device_context" oyX1,
SANE,
CUPS,
oyRE
out: not required
"SANE_Device"
"ppd_file_t*"
"libraw_output_params_t*"
out[d]: string
device handles SANE,
CUPS, oyRE
version + SANE_Device + SANE_Handle
out: device handle caching
out[c]: oyCMMptr_s or oyOption_SetFromData() but no string(s)

Note: If a "manufacturer" or a "model" option appear in a device after the "list" call, the device is considered ready for a Oyranos DB query. Thus all options which normally appear after a "properties" call should be included together with "manufacturer" or "model" options.


"properties" call
Property Modules Informations Data format
"command"="properties" oyX1, SANE, CUPS, oyRE in[r]: call for even expensive informations
in: string
"device_name" oyX1, SANE, CUPS, oyRE in: select a single device;
out: ID of each device, e.g. <manufacturer>-<model>
in(oyConfigs_FromPattern)/out[c]: string
"display_name" oyX1 in: select a X11 display and get all connected devices; "device_name" has priority in(oyConfigs_FromPattern): string
"manufacturer" oyX1, SANE, CUPS, oyRE out[r]: device manufacturer out[c]: string
"model" oyX1, SANE, CUPS, oyRE out[r]: device model out[c]: string
"serial" oyX1, SANE, CUPS, oyRE out: device serial number out[c]: string
"system_port" oyX1,
SANE,
CUPS,
oyRE
out: X11 screen number
out: scsi/usb/parallel port?
out: print queue?
out: RAW file name?
out[c]: string
"host" oyX1,
SANE,
CUPS,
oyRE
out: X11 server host name
out: possible?t
out: print host possible?
out: "local" host?
out[c]: string
"display_geometry" oyX1 out[r]: X11 screen geometry as in "device_rectangle" out[c]: string
"edid" oyX1 out: monitor EDID block in: string
out[d]: use oyOption_SetFromData(); users - oyOption_GetData()
"device_context" oyX1,
SANE,
CUPS,
oyRE
in: not required
SANE_Device
ppd_file_t*?
libraw_output_params_t*
in: add with oyOption_SetFromData()
device handles SANE, CUPS, oyRE in: abreviation to talk with drivers in[c]: oyOption_GetData()
device settings oyX1,
SANE,
CUPS,
oyRE
out[r]: "display_geometry" ...
...
static colour related PPD attributes
libraw options
out[c]: string


"setup" call
Property Modules Informations Data format
"command"="setup" oyX1,
SANE,
CUPS,
oyRE
in[r]: call for uploading a ICC profile through the device driver
do nothing
set a cupsICCProfile attribute in a given PPD and write out to file
do nothing
in: string
"device_name" oyX1, SANE, CUPS in[r]: select a single device in(oyConfigs_FromPattern): string
"profile_name" oyX1, SANE, CUPS in[r]: the local accessible ICC profile file name in: string
"config_file" CUPS in: a PPD configuration file (ppd_file_t*) to modify or nothing; out: (ppd_file_t*) in: oyOption_GetData(); out[d]: oyOption_SetFromData()?
device handles SANE, CUPS, oyRE in: abreviation to talk with drivers in[c]: oyOption_GetData()


"unset" call
Property Modules Informations Data format
"command"="unset" oyX1,
SANE,
CUPS,
oyRE
in[r]: unloading the _ICC_PROFILE_xxx atom
do nothing
remove a cupsICCProfile attribute in a given PPD
do nothing
in: string
"device_name" oyX1, SANE, CUPS in[r]: select a single device in(oyConfigs_FromPattern): string
"profile_name" oyX1, SANE, CUPS in[r]: the local accessible ICC profile file name in: string
"config_file" CUPS in: a PPD configuration file (ppd_file_t*) to modify or nothing; out: (ppd_file_t*) in: oyOption_GetData(); out[d]: oyOption_SetFromData()?
device handles SANE, CUPS, oyRE in: abreviation to talk with drivers in[c]: oyOption_GetData()


"help" call
Property Modules Informations Data format
"command"="help" oyX1, SANE, CUPS, oyRE in[r]: show help text through the modules local oyMessage_f in: string

Calling a device module without any command or a unknown command shall issue a message through the modules local oyMessage_f. The message shall contain infos about, describing calls and their properties and the expected results. Otherwise adhering to the above protocol will enshure a base level of interoperability with users like KM.

How to create a useful "device_name" (ID)?

it should be unique in that the module can distinguish each device and understand to build a device context. This is important for the case when no device context pointer/handle is passed from the user. How that is defined is up to the module writer. Even though, a string, one which makes sense in KM, would be much appreciated. e.g. in oyX1 it is "device_name"=":0.1" or "device_name"="far-away.org:10.0". The modules XOpenDisplay() can directly use these strings and the module can create a context and talk to the device. For SANE you have choosen "pnm:0", "pnm:1" and here locally I see "plustek:libusb:003:002". The last is unfortunedly subject to change with a new usb port or after newly plugging in. But that seems accepable.


Handling device contexts

The "device_context" option can be set from the module during the "list" call into a device. The user can then see, which specific information is accepted by the module. The module has implicitely to assume, that the user has no background about the called device class, and to initialise a device by its own. In case the user has already a context and passes this one to Oyranos, the module needs to extract the colour related device settings from this and pass the device settings as string to Oyranos. Oyranos will then be able to search for a according ICC profile.

It is important for Oyranos, the module and the user to agree who is responsible for the driver contexts. oyOption_SetFromData() is useful to pass a pointer through a oyOption_s. The size argument can be set to zero to avoid freeing the pointer through Oyranos. In case the module provides a context, e.g. in "list" then that needs to be released through driver functions. Oyranos has the oyCMMptr_s struct defined in oyranos_cmm.h which can be used: [1] (http://www.oyranos.org/doc_intern/structoyCMMptr__s.html).

Multiple Configurations per "device_name"

For backends its possible to resolve one "device_name" option to multiple driver configurations. Such backends are best implemented in that they resolve the oyConfig_s objects right from the beginning, e.g. the "list" call. Otherwise the oyConfig_s devices are not uniquely defined. On a practical example, a CUPS device would be uniquely defined, if all colour related and to be included PPD entries are included in the oyConfig_s::backend_core options as strings.

Users can subsummarise such devices in that they look at the registration, manufacturer, model and serial number strings. However they should make clear that each device consists as well of the driver settings.