![]() |
Oyranos Colour Management System API |
Oyranos core <-> device module protocol
Copyright: Kai-Uwe Behrmann, Yiannis Belias @ 2009Oyranos 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.
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.
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.
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 |
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() |
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() |
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.
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.
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).
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.