DEVICETYPE implementations provided by the SDK

DEVICETYPE implementations provided by the SDK. More...

Files
file	devutils.h
	Contains functions which can be shared between multiple devices.
file	kitdevs.h
	Device and IOCTL numbers for SDK devices.
file	namedcolordev.h
	Example of a PostScript device type to implement named color lookup.
file	pgbdev.h
	Page buffer device functions.
file	photoinkdev.h
	Example of a PostScript device type to implement photoink splitting.
file	streamdev.h
	Functions for interfacing the skinkit streaming device with the client stream implementations.
file	caldev.c
	Implementation of the calendar device type. See Postscript Language Reference Supplement for Version 2 (Pages 150-151).
file	config.c
	Implementation of the %config% (configuration) device type.
file	devparam.h
	Contains definitions shared between the PageBuffer (pgbdev) and Screening (scrndev) example device implememtations.
file	devutils.c
	Contains functions which can be shared between multiple devices.
file	fdecrypt.c
	Example implementation of the font decoder filter.
file	filedev.c
	Implementation of the file system device type.
file	fndcrypt.c
	Example implementation of the font decoder and encoder filter. If you wish to just test font decoding, define TEST_DECRYPTFONT instead. There are two encryption algorithms supported, to show how to implement multiple strategies.
file	monitor.c
	The monitor device type. This implements standard input and output for the rip.
file	namedcolordev.c
	Example of a PostScript device type to implement named color lookup. This example is unusual in that it is split into two files.
file	pgbdev.c
	The implementation of the %pagebuffer% device.
file	photoinkdev.c
	Example of a PostScript device type to implement photoink splitting. This example is unusual in that it is split into two files. The photoinksplitter.c file is in skintest. It contains the device specific code for light/dark splitting algorithms. The photoinkdev.c file (this file) contains boilerplate code for a PostScript device that acts as the intermediary between the RIP and the photoink splitting algorithms. This file is not expected to require any changes.
file	preboot.c
	Implementation of the preboot device type.
file	progdev.c
	Implementation of an example progress device.
file	ramdev.c
	Implementation of a filesystem device tied to in-memory data.
file	scrndev.c
	An example implementation of an AM screen parameter capture device.
file	scrndev.h
	Describes interface shared between the Screening (scrndev) and PageBuffer (pgbdev) example device implementations.
file	sockdev.c
	Implementation of socket input device type.
file	streamdev.c
	Implementation of an input/output device tied to a stream reader.
file	uniondev.c
	Implementation of the union device type.

Macros
#define	OEM_NUMBER   0xffff0000
#define	MONITOR_DEVICE_TYPE   ( OEM_NUMBER | 1 )
	Required output log and console device.
#define	CONFIG_DEVICE_TYPE   ( OEM_NUMBER | 2 )
	Required %config% device implementation.
#define	PAGEBUFFER_DEVICE_TYPE   ( OEM_NUMBER | 3 )
	Required %pagebuffer% device implementation.
#define	SCREENING_DEVICE_TYPE   ( OEM_NUMBER | 4 )
	Optional screening export device, for use with RLE output.
#define	CALENDAR_DEVICE_TYPE   ( OEM_NUMBER | 5 )
	Optional persistent calendar device implementation.
#define	STREAM_DEVICE_TYPE   ( OEM_NUMBER | 6 )
	Optional device to input and output to stream abstraction.
#define	SOCKET_DEVICE_TYPE   ( OEM_NUMBER | 7 )
	Optional device to input from and output to network socket.
#define	RAM_DEVICE_TYPE   ( OEM_NUMBER | 8 )
	Optional RAM based filesystem device implementation.
#define	PROGRESS_DEVICE_TYPE   ( OEM_NUMBER | 11 )
	Optional progress reporting device.
#define	NAMEDCOLOR_DEVICE_TYPE   ( OEM_NUMBER | 15 )
	Optional named color lookup device.
#define	PHOTOINK_DEVICE_TYPE   ( OEM_NUMBER | 16 )
	Optional PhotoInk splitting device.
#define	CMM_PARAMS_DEVICE_TYPE   ( OEM_NUMBER | 17 )
	Optional CMM params device.
#define	DeviceIOCtl_EndPage   ( OEM_NUMBER | 1 )
	IOCTL operator code for ending page. This allows devices to implement a device-specific page ending procedure.
#define	DeviceIOCtl_SetCompressionMode   ( OEM_NUMBER | 2 )
	IOCTL opcode for setting the compression mode when storing files on resource-limited devices. The RAM device implements this opcode.
#define	IOCTL_COMPRESSION_OFF   0
	Parameter value for DeviceIOCtl_SetCompressionMode to disable compression.
#define	IOCTL_COMPRESSION_ON   1
	Parameter value for DeviceIOCtl_SetCompressionMode to enable compression.

Functions
DEVICE_result	KMapPlatformError (int32 pkError)
	Provides a mapping from the skin platform error codes to their nearest equivalent RIP device code. More...
HqBool	SubDeviceMount (DEVICELIST *dev, DEVICELIST **pSub, const char *subname, DEVICETYPE *subdevtype)
	Allocate and mount a private instance of a devicetype for use by a parent device. More...
HqBool	SubDeviceDismount (DEVICELIST *dev, DEVICELIST **pSub)
	Dismount and free a private instance of a devicetype. More...
HqBool	param_match_name (const DEVICEPARAM *param, const uint8 *name, int32 namelen)
	Utility function for device implementations to match incoming parameter name to a string. More...
HqBool	param_match_cname (const DEVICEPARAM *param, const char *name, size_t namelen)
	Utility function for device implementations to match incoming parameter name to a C string. More...
void	param_store_name (DEVICEPARAM *param, uint8 *name, int32 length)
	Utility function for device implementations to store a parameter name in a DEVICEPARAM. This function exists mainly for clients to use STRING_AND_NAME() to set parameter names to constant strings. More...
void	param_store_string (DEVICEPARAM *param, uint8 *str, int32 length)
	Utility function for device implementations to store a string value in a DEVICEPARAM. This function exists mainly for clients to use STRING_AND_NAME() to set parameter values to constant strings. More...
HqBool	SwLeGetIntDevParam (DEVICELIST *pDev, uint8 *pszParamName, int32 *pInt)
	A convenience function to get the current value of an integer device parameter. More...
HqBool	SwLeGetBoolDevParam (DEVICELIST *pDev, uint8 *pszParamName, HqBool *pBool)
	A convenience function to get the current value of a boolean device parameter. More...
HqBool	SwLeGetFloatDevParam (DEVICELIST *pDev, uint8 *pszParamName, float *pFloat)
	A convenience function to get the current value of a floating-point (real) device parameter. More...
HqBool	SwLeGetStringDevParam (DEVICELIST *pDev, uint8 *pszParamName, uint8 **ppStr, int32 *pStrLen)
	A convenience function to get the current value of a string device parameter. More...

Detailed Description

DEVICETYPE implementations provided by the SDK.

The device abstraction is a fundamental mechanism by which the Core RIP communicates with its environment, and by which PostScript configuration can communicate with compiled C code.

Devices are usually mounted by the SW/Sys/ExtraDevices file, with the device number providing the mechanism to connect to the DEVICETYPE definition in C.

With the exception of the device types with specific numbers below, all device types you define should have numbers in which the most significant 16 bits are the OEM number allocated to you as a developer. For the purposes of these examples, the number 0xffff is used: this value is reserved for private use in closed environments, and can also be used. It will not conflict with any other numbers already used within the system.

The choice of the least significant 16 bits is arbitrary: so long as the numbers used in the SW/Sys/ExtraDevices file are consistent with those used in the C, everything should work.

You are expected to provide an implementation of the following device types. The SDK includes implementations of these which may be used or modified:

• OS_DEVICE_TYPE (device type 0) This is the file system device. The SDK contains a simple implementation of the file system device in filedev.c.
• PREBOOT_DEVICE_TYPE (device type 18) The preboot device. If a device of this type is present, it can be used to mount and configure other devices, including the %os% device, before booting the RIP. The main purpose of this device is to allow mounting of the %os% device on a non filesystem device; see the preboot device implementation in the SDK for details of this device's protocol. The SDK contains an implementation of the preboot device in preboot.c.
• CONFIG_DEVICE_TYPE The config device is a source of job data for the RIP's server loop. The SDK contains an implementation of the configuration device in config.c.
• MONITOR_DEVICE_TYPE The monitor device implements a legacy method of writing data to the RIP's output channel and log files. The SDK monitor device in the SDK is also used as a source of data for jobs. The SDK contains an implementation of the monitor device in monitor.c.
• PAGEBUFFER_DEVICE_TYPE The pagebuffer device is the destination for raster data from the core. The pagebuffer device interface is not documented by Global Graphics. The SDK contains an implementation of the pagebuffer device in pgbdev.c. Global Graphics does not recommend modifying the pagebuffer device if possible. This interface will be withdrawn in a future release.

A number of devices are implemented in the SDK, and may be linked into a RIP product as-is, or used as as examples to help build production-ready devices. These devices are optional, but some functionality will be lost if some of them are excluded from a RIP product:

• CALENDAR_DEVICE_TYPE The calendar device is an optional device used to supply real time clock information to the core. The SDK contains an implementation of the calendar device in caldev.c that uses the OS's C library support for localtime() for the date and time.
• RAM_DEVICE_TYPE This is a file system device that stores its entire file system tree in RAM. The SDK contains an implementation of a RAM device that can be configured with a pre-built file system tree in memory, or can be configured with an empty file system. The RAM device can be used as a layer for union file systems. The SDK contains an implementation of a RAM device in ramdev.c.
• UNION_DEVICE_TYPE This is a file system device that presents multiple file system devices as a single device, with files on the higher priority devices masking the lower priority devices. The union device is useful when running multiple RIPs on a single machine, to share a read-only SW filesystem with a unique writable filesystem for each RIP instance. The SDK contains an implementation of a union device in uniondev.c.
• FONT_ND_CRYPT_DEVICE_TYPE The RIP can use the DEVICETYPE abstraction to implement filters. The SDK may contain examples of font decryption and encryption filters in fdecrypt.c and fndcrypt.c, which show how to protect character data and outlines from fonts.
• NAMEDCOLOR_DEVICE_TYPE A named color device is provided in the SDK, to show how custom named color database lookups and tint transforms can be provided from C code. The implementation of this device is split across the SDK and the skin components, with the SDK containing the generic code and the skin components containing some small pre-built example color tables. The SDK contains an implementation of the named color device in namedcolordev.c.
• PROGRESS_DEVICE_TYPE This is an optional device type. If present, the RIP opens files to represent progress reading files, and also sends some job timing information to this device. All of the information sent to the progress device can now be obtained in convenient ways through timelines and through the progress monitor event channel. The SDK contains an implementation of this device in progdev.c.
• SCREENING_DEVICE_TYPE When outputting RLE, the RIP can optionally export spot function screen definitions to a screening device, which can store and use the screen definitions to convert the RLE output to halftoned output. The SDK contains an example implementation of a screening device in scrndev.c. This should not be confused with the modular screening interface, this device is a different interface for a very different purpose.
• SOCKET_DEVICE_TYPE RIP products may wish to send files to or from other processes or machines. The socket device implemented in sockdev.c implements a simple example of how to open, read, and write to TCP/IP sockets. The /Address and /Port parameters set the network address and port that the socket device will read or write to.

There are a small number of device types already built into the rip which are available for OEM use. See the DEVICE interface for details.

Utility functions for working with devices include:

• KMapPlatformError() to map PKError file handling results to DEVICE_result result codes.
• SubDeviceMount() and SubDeviceDismount() to mount a private instance of a device type. This instance is not findable by SwFindDevice() or accessible from PostScript.
• param_match_name() and param_match_cname() to assist writing DEVICELIST_GET_PARAM functions by matching parameter names.
• param_store_name() and param_store_string() to assist writing DEVICELIST_GET_PARAM functions by storing parameter names and string values.
• SwLeGetIntDevParam(), SwLeGetBoolDevParam(), SwLeGetFloatDevParam(), and SwLeGetStringDevParam() to retrieve the values of a named parameter from a device.

Macro Definition Documentation

OEM_NUMBER

#define OEM_NUMBER   0xffff0000

Private number to use for SDK-supplied devices. If you change this, you will also have to change the device type mounts in Sys/ExtraDevices.

Function Documentation

KMapPlatformError()

DEVICE_result KMapPlatformError

(

int32

pkError

)

Provides a mapping from the skin platform error codes to their nearest equivalent RIP device code.

Parameters

[in]

pkError

Skin error code.

Returns

Equivalent error code for the RIP device interface.

param_match_cname()

HqBool param_match_cname	(	const DEVICEPARAM *	param,
		const char *	name,
		size_t	namelen
	)

Utility function for device implementations to match incoming parameter name to a C string.

Parameters

[in]	param	Parameter to match.
[in]	name	Name to match
	namelen	Length of name, or zero if NUL-terminated and the caller does not know the length.

Return values

TRUE	if the parameter name matches
FALSE	if the parameter name does not match.

param_match_name()

HqBool param_match_name	(	const DEVICEPARAM *	param,
		const uint8 *	name,
		int32	namelen
	)

Utility function for device implementations to match incoming parameter name to a string.

Parameters

[in]	param	Parameter to match.
[in]	name	Name to match
	namelen	Length of name.

Return values

TRUE	if the parameter name matches
FALSE	if the parameter name does not match.

param_store_name()

void param_store_name	(	DEVICEPARAM *	param,
		uint8 *	name,
		int32	length
	)

Utility function for device implementations to store a parameter name in a DEVICEPARAM. This function exists mainly for clients to use STRING_AND_NAME() to set parameter names to constant strings.

Parameters

[in]	param	Parameter to store name in.
[in]	name	Name to store.
	length	Length of name, or zero if NUL-terminated and the caller does not know the length.

param_store_string()

void param_store_string	(	DEVICEPARAM *	param,
		uint8 *	str,
		int32	length
	)

Utility function for device implementations to store a string value in a DEVICEPARAM. This function exists mainly for clients to use STRING_AND_NAME() to set parameter values to constant strings.

Parameters

[in]	param	Parameter to store string value in.
[in]	str	String to store.
	length	Length of str, or zero if NUL-terminated and the caller does not know the length.

SubDeviceDismount()

HqBool SubDeviceDismount	(	DEVICELIST *	dev,
		DEVICELIST **	pSub
	)

Dismount and free a private instance of a devicetype.

Parameters

dev	The parent device.
pSub	A location where the sub-device pointer to dismount and free is stored.

Return values

TRUE	The sub-device dismounted without error. The parent device's error status was not changed.
FALSE	The sub-device dismounted with and error. The error was propagated to the parent device dev.

On exit, the memory for the sub-device is always freed.

SubDeviceMount()

HqBool SubDeviceMount	(	DEVICELIST *	dev,
		DEVICELIST **	pSub,
		const char *	subname,
		DEVICETYPE *	subdevtype
	)

Allocate and mount a private instance of a devicetype for use by a parent device.

Parameters

dev	The parent device.
pSub	A location where the new sub-device pointer will be stored.
subname	The suffix of the sub-device. The sub-device name will be constructed from the parent device name and this suffix. The sub-device is not discoverable through SwFindDevice.
subdevtype	The device type for the sub-device.

Return values

TRUE	The sub-device was allocated and initialised without error. The parent device's error status was not changed.
FALSE	The sub-device could not be allocated or initialised. The parent device's last error is set to indicate the failure.

Allocate and mount a private instance of a devicetype for use by a parent device.

SwLeGetBoolDevParam()

HqBool SwLeGetBoolDevParam	(	DEVICELIST *	pDev,
		uint8 *	pszParamName,
		HqBool *	pBool
	)

A convenience function to get the current value of a boolean device parameter.

Parameters

pDev	The device to get the parameter value from. It is safe to pass NULL, but the function will fail and return FALSE.
pszParamName	zero-terminated name of the required parameter.
pBool	If the function succeeds, this receives the current value of the specified device parameter. If the function fails, the contents are left undefined.

Returns

TRUE if the function succeeds, otherwise FALSE.

SwLeGetFloatDevParam()

HqBool SwLeGetFloatDevParam	(	DEVICELIST *	pDev,
		uint8 *	pszParamName,
		float *	pFloat
	)

A convenience function to get the current value of a floating-point (real) device parameter.

For full documentation, see SwLeGetIntDevParam(). The contract of this function is the same, except that it specializes for floats instead of integers.

Parameters

pDev	The device to get the parameter value from. It is safe to pass NULL, but the function will fail and return FALSE.
pszParamName	zero-terminated name of the required parameter.
pFloat	If the function succeeds, this receives the current value of the specified device parameter. If the function fails, the contents are left undefined.

Returns

TRUE if the function succeeds, otherwise FALSE.

SwLeGetIntDevParam()

HqBool SwLeGetIntDevParam	(	DEVICELIST *	pDev,
		uint8 *	pszParamName,
		int32 *	pInt
	)

A convenience function to get the current value of an integer device parameter.

Parameters

pDev	The device to get the parameter value from. It is safe to pass NULL, but the function will fail and return FALSE.
pszParamName	zero-terminated name of the required parameter. This should not use PostScript syntax - there should be no leading slash. For example, "PageNumber" is correct, while "/PageNumber" is not.
pInt	If the function succeeds, this receives the current value of the specified device parameter. If the function fails, the contents are left undefined.

Returns

TRUE if the function succeeds; FALSE if the function fails. Reasons why the function may fail include the following:-

• NULL was passed as pDev.
• The device handle is no longer valid, because the device was dismounted since the handle was obtained.
• The name of the parameter is unknown to the device. It might be mis-spelled, for instance, or have a spurious leading slash character.
• The parameter is not of integer type.

This convenience routine does not distinguish between the reasons for failure. Use the core RIP interface directly for richer diagnostics.

SwLeGetStringDevParam()

HqBool SwLeGetStringDevParam	(	DEVICELIST *	pDev,
		uint8 *	pszParamName,
		uint8 **	ppStr,
		int32 *	pStrLen
	)

A convenience function to get the current value of a string device parameter.

For full documentation, see SwLeGetIntDevParam(). The contract of this function is the same, except that it specializes for strings instead of integers.

The string memory returned by this function is owned by the underlying device, not by the caller. The caller should not free the string. The caller should make its own copy if the data is needed persistently.

Parameters

pDev	The device to get the parameter value from. It is safe to pass NULL, but the function will fail and return FALSE.
pszParamName	zero-terminated name of the required parameter.
ppStr	If the function succeeds, this receives a pointer to the parameter value. This string data is not necessarily zero-terminated. The length of the string's valid portion is returned separately. If the function fails, the contents are undefined.
pStrLen	If the function succeeds, this receives the number of valid character bytes in the string. If the function fails, the contents are undefined.

Returns

TRUE if the function succeeds, otherwise FALSE.