The Harlequin RIP SDK provides an integration library that provides required platform and library dependencies for the Harlequin core library, and simplifies and enhances its use and functionality. More...

Modules
	Hot folder support
	Hot folder support.

	Harlequin SDK input queue
	This is the Harlequin SDK implementation of the input queue API.

	DEVICETYPE implementations provided by the SDK
	DEVICETYPE implementations provided by the SDK.

	SDK memory handling functions

	In-memory virtual file system

	File and path manipulation functions
	Harlequin SDK file and path manipulation functions.

	Harlequin SDK timing and profiling subsystem
	The Harlequin RIP timing and profiling system is used to capture high frequency information about the internal operation of the Harlequin RIP, and to control profiling. It is not normally built into release RIPs.

	Functions for outputting messages from the skin

	Tiling methods provided by the SDK
	Tiling method API implementations provided by the SDK.

Files
file	hhrsdk.h
	Combined include file for all headers in Harlequin RIP SDK.

file	hqnstrutils.h
	String-related utility functions.

file	ktime.h
	Time related utility functions.

file	progevts.h
	Progress event control.

file	skinkit.h
	Main entry points for Harlequin SDK skinkit API.

file	skinsignal.h
	Platform Ctrl-C handling abstraction. Each platform can have its own implementation of these functions.

file	skintimeline.h
	Skinkit timelines. This file is separate from skinkit.h to avoid having to include the timeline library from all client paths.

file	streams.h
	A simple streaming abstraction to handle RIP I/O when using the Reference API.

file	psock.c
	Socket related utility functions for Windows. See psock.h.

file	kit.h
	Exports to other skinkit files from skinkit.c.

file	lsgrace.h
	Functions for interfacing the skinkit XPS input device with the client stream implementations.

file	psock.h
	Socket related utility functions with per-platform implementations.

file	ripthread.c
	Example implementation of corerip integration: Starting the RIP.

file	ripthread.h
	RIP lifecycle code.

file	skinkit.c
	This file implements the interface between the "push" model of the `SwLe` example skin functions, and the natural "pull" model of the core Harlequin RIP interface. It does this by synchronizing the thread on which the RIP is running with the calling application thread.

file	strutils.c
	String-related utility functions.

file	sync.c
	Synchronization between the application calling thread and the thread that is running the RIP. Having this synchronization simplifies the application code because it doesn't need to worry about callbacks on the monitor or raster functions happening asynchronously - they will only happen when the application has called into one of the SwLe functions and is blocked waiting for the result.

file	sync.h
	Cross platform synchronization primitives.

file	zlibutil.h
	zlib utilities

Data Structures
struct	SwLeDoParams
	A structure containing the parameters for SwLeDo(). More...

struct	SkinDynamicBuffer
	Dynamically-allocated buffer structure used to collect configuration PostScript for a job. More...

Macros
#define	SW_LE_STOP_PS "/HqnConfigProvider /ProcSet findresource /quitrip get exec"
	PostScript to shut down the RIP. More...

#define	SWLEDO_HAS_PARAM(params_, field_) ((params_) != NULL && (params_)->size >= offsetof(SwLeDoParams, field_) + sizeof((params_)->field_))
	Given a pointer to a SwLeDoParams structure, is a named field present?

#define	SKIN_DYNAMIC_BUFFER_INIT {NULL, 0, 0}
	Auto and static scope initialiser for configuration data buffers.

Typedefs
typedef void()	SwLeMONITORCALLBACK(uint32 cbBuffer, const uint8 *pBuffer)
	The type of a callback function which receives monitor information from the RIP for the current job. More...

typedef void()	SwLeRIPEXITCALLBACK(int32 errorCode, const uint8 *pszText)
	The type of a callback function which is called when the RIP exits. Used in SwLeSetRipExitFunction(). More...

typedef void()	SwLeRIPREBOOTCALLBACK(void)
	The type of a callback function which is called when the RIP reboots. Used in SwLeSetRipRebootFunction().

typedef struct SwLeDoParams	SwLeDoParams
	A structure containing the parameters for SwLeDo().

typedef int32()	SwLeParamCallback(void pJobContext, const void param)
	The type of callback functions triggered when a parameter is changed. More...

typedef struct SkinDynamicBuffer	SkinDynamicBuffer
	Dynamically-allocated buffer structure used to collect configuration PostScript for a job. More...

Enumerations
enum	SwLeProcessQueueResult { SW_LE_QUEUE_EMPTY = 0 , SW_LE_QUEUE_JOB_OK = 1 , SW_LE_QUEUE_JOB_ERROR = 2 , SW_LE_QUEUE_NO_RIP = 3 }
	Return values for SwLeProcessInputQueue() and SwLeProcessJobs(). More...

enum	SwLeProcessOp { SW_LE_DO_INITRUNTIME , SW_LE_DO_SDK_START , SW_LE_DO_RIP_MEMINIT , SW_LE_DO_RIP_START , SW_LE_DO_PROCESS_QUEUE , SW_LE_DO_RIP_STOP , SW_LE_DO_SHUTDOWN }
	Operations for SwLeDo(). More...

Functions
HqBool	SwLeInitRuntime (void *pContext)
	Initializes skinkit variables prior to starting the RIP. More...

HqBool	SwLeSDKStart (size_t RIP_maxAddressSpaceInBytes, size_t RIP_workingSizeInBytes, void pMemory, SysMemFns pSysMemFns, uint8 **reasonText)
	Initialise SDK support libraries for the RIP. More...

void	SwLeSDKEnd (int32 exitCode)
	Shutdown the SDK support libraries. More...

void	SwLeMemInit (size_t RIP_maxAddressSpaceInBytes, size_t RIP_workingSizeInBytes, size_t RIP_emergencySizeInBytes, void *pMemory)
	Pre-initializes the RIP, giving it the memory arena prepared by SwLeSDKStart(). More...

HqBool	SwLeAddCustomDevices (int32 nCustomDevices, DEVICETYPE **ppCustomDevices)
	Makes DEVICETYPE objects available for discovery by the RIP. More...

HqBool	SwLeStart (size_t RIP_maxAddressSpaceInBytes, size_t RIP_workingSizeInBytes, size_t RIP_emergencySizeInBytes, void pMemory, SwLeMONITORCALLBACK pfnMonitor)
	Starts the Harlequin RIP, giving it the memory arena prepared by SwLeSDKStart(). More...

void	SwLeSetRipExitFunction (SwLeRIPEXITCALLBACK *pfnRipExit)
	Supply a callback function to be called when the RIP exits. More...

void	SwLeSetRipRebootFunction (SwLeRIPREBOOTCALLBACK *pfnRipReboot)
	Supply a callback function to be called when the RIP reboots. More...

void	SwLeSetRipRendererThreads (int32 nThreads)
	Sets the number of renderer threads. More...

int32	SwLeStop (void)
	Request that the RIP shutdown. More...

int32	SwLeExitCode (void)
	Returns the exit status of the RIP. More...

void	SwLeShutdown (void)
	Performs shutdown operations when the application exits. More...

HqBool	SwLeSetJobName (const uint8 *name, size_t namelen)
	Low-level function to set the job name used by the next job invoked by SwLeJobStart(). More...

void	SwLeSetJobNumber (int32 jobno)
	Low-level function to set the job number used by the next job invoked by SwLeJobStart(). More...

HqBool	SwLeJobStart (uint32 cbBuffer, uint8 pBuffer, void pJobContext)
	Low-level function to prepare the Harlequin RIP to receive a PostScript language job. More...

HqBool	SwLePs (uint32 cbBuffer, uint8 *pBuffer)
	Low-level function to pass a chunk of PostScript language data to the Harlequin RIP. More...

HqBool	SwLeJobEnd (void)
	Low-level function to terminate the current job. More...

int32	SwLeDo (int32 op, SwLeDoParams *params)
	Perform required operations to reach the requested SDK and RIP state. More...

int32	SwLeProcessInputQueue (void)
	Process a job from the skin's input queue implementation. More...

int32	SwLeProcessJobs (SwLeDoParams *params)
	Process jobs from the input queue using SwLeProcessInputQueue() until there are no more jobs and (optionally) no more input sources. More...

HqBool	SwLeInJob (void)
	Low-level function to indicate if the skin is within a job. More...

HqBool	SwLeProcessingError (void)
	Low-level function to indicate whether an error occurred in the most recent chunk of job data that was processed by the RIP. More...

struct sw_data_api *	GetDataAPI (void)
	Get and cache the data API pointer. More...

HqBool	SkinDynamicBufferAdd (SkinDynamicBuffer buffer, const char format,...)
	Helper function to write formatted string (using swncopyf()) to the end of a dynamic buffer, extending the buffer as necessary. More...

void	SkinDynamicBufferReset (SkinDynamicBuffer *buffer)
	Reset a dynamic buffer to contain no data, but preserve the existing allocated memory. More...

void	SkinDynamicBufferFree (SkinDynamicBuffer *buffer)
	Free any memory allocated for dynamic buffer data. More...

void	SwLeSetHqAssertHandlers (HqAssertHandlers_t *handlers)
	Set the HQASSERT() and HQTRACE() handler functions to be used by the Skin, SDK and the RIP. More...

HqBool	KSetSystemErrorLevel (int32 errlevel)
	Set system error record level. More...

int32	KGetSystemErrorLevel (void)
	Get system error record level set by KSetSystemErrorLevel().

void	PKRecordSystemError (int32 errcode, int32 errline, const char *pErrfile, HqBool fSysErr)
	Record through the monitor callback system errors according to the error level set by KSetSystemErrorLevel(). More...

Detailed Description

The Harlequin RIP SDK provides an integration library that provides required platform and library dependencies for the Harlequin core library, and simplifies and enhances its use and functionality.

The Harlequin RIP SDK provides interfaces to control the SDK and RIP operation; it provides operating-system specific filesystem and other devices for the core library; the RDR, Event and Timeline libraries required by the core library; the input queueing API implementation; hot folder input support; framebuffer and eHVD output support; tiling method implementations, and other capabilities.

See Harlequin RIP skin interfaces.

Control flow functions

The SwLeDo() function is the preferred method for controlling the Harlequin SDK and RIP. SwLeDo() is called with a parameters structure and an operation. It will call the SDK and RIP control flow functions in the correct order, with the right parameters, to arrive at the target state for the operation. The operation can start up the SDK, the RIP, process jobs, shut down the RIP and/or shutdown the SDK, including rebooting the RIP and or SDK, without you having to manage the steps individually. The steps performed by SwLeDo() and the control flow functions they call are described in the SwLeProcessOp description.

The control flow functions called by SwLeDo() are SwLeInitRuntime(), SwLeSDKStart(), SwLeMemInit(), SwLeStart(), SwLeProcessJobs(), SwLeStop(), SwLeSDKEnd() and SwLeShutdown(). The calls to these functions described in this section will all be made in the correct sequence when using SwLeDo().

Other SDK initialization functions provided by the SDK library are:

SwLeSetHqAssertHandlers() is used to install custom handlers for the assert and trace handlers in the SDK and RIP.
SwLeSetRipExitFunction() may be used to set a function that is called when the RIP exits.
SwLeSetRipRebootFunction() may be used to set a function that is called when the RIP reboots.
SwLeSetRipRendererThreads() may be used to set the number of threads that the RIP can use (subject to licensing restrictions).
SwLeAddCustomDevices() is used to add integration-specific devices. It is normally called immediately after SwLeSDKStart() to add devices, but may actually be used any time between SwLeSDKStart() and SwLeSDKEnd().

After the RIP exits, SwLeExitCode() may be called to access the RIP's exit status.

Input queue job processing functions

The input queue job processing functions take one or more jobs from the input queue and submit them to the RIP (see Input queue and source API and Harlequin SDK input queue). Global Graphics highly recommends that you use these functions instead of the Low-level job processing functions. The input queue job processing functions perform correct setup to automatically detect the job type, to apply the configuration and overrides, and ensure the job is submitted in a way that will not leak server loop memory.

SwLeProcessInputQueue() takes a single job from the input queue, creates a configuration job for it, submits it to the RIP, and waits for the job to complete. SwLeProcessInputQueue() does not block if there are no jobs on the input queue.

SwLeProcessJobs() processes multiple jobs from the input queue, optionally waiting for more jobs to arrive if there are persistent input sources registered.

Low-level job processing functions

The input queue job processing functions construct PostScript that configures the RIP and presents the input job as the data stream. They use these low level job processing functions to perform parts of their processing. It is not normally necessary for you to call these functions directly. Global Graphics highly recommends that you use the Input queue job processing functions instead of these functions. Using these functions directly risks incorrectly configuring the RIP and leaking server loop memory.

SwLeSetJobName() and SwLeSetJobNumber() may be used to set the job name and number for the next SwLeJobStart().

SwLeJobStart() submits configuration data to the RIP to initiate running a job, and waits for the RIP to accept it.

SwLePs() provides a buffer of PostScript job data to the RIP, and waits for the RIP to accept it. This function is not used by the input queue processing functions: they present the job data stream to the RIP as part of the configuration data in SwLeJobStart().

SwLeJobEnd() indicates to the RIP that all data for a job has been sent, and waits for the RIP to respond.

SwLeInJob() is an inquiry function that indicates if SwLeJobStart() has been called, but the matching SwLeJobEnd() has not yet been called.

SwLeProcessingError() is an inquiry function that indices that the most recent chunk of data processed by the RIP raised an error.

Utility functions

In addition to these, some utility functions are provided:

SkinDynamicBufferReset(), SkinDynamicBufferAdd(), and SkinDynamicBufferFree() are used to append formatted strings to a contiguous memory buffer, extending as necessary. These functions are used to construct configuration and override data used in submitting jobs to the RIP.

GetDataAPI() returns a pointer to the RDR_API_DATA API registered by the core library. This function is useful in raster backends and other functions which may have been passed a structured data pointer from the core library.

KSetSystemErrorLevel(), KGetSystemErrorLevel(), and PKRecordSystemError() may be used to capture and monitor operating system call errors.

Macro Definition Documentation

◆ SW_LE_STOP_PS

#define SW_LE_STOP_PS "/HqnConfigProvider /ProcSet findresource /quitrip get exec"

PostScript to shut down the RIP.

This is the special PostScript used to shutdown the RIP. It is submitted as a job by SwLeStop(), or as the override PS for a config-only job via the input queue for signal handling.

Typedef Documentation

◆ SkinDynamicBuffer

typedef struct SkinDynamicBuffer SkinDynamicBuffer

Dynamically-allocated buffer structure used to collect configuration PostScript for a job.

For auto and static scope variables of this type, the initialiser SKIN_DYNAMIC_BUFFER_INIT should be used.

◆ SwLeMONITORCALLBACK

typedef void() SwLeMONITORCALLBACK(uint32 cbBuffer, const uint8 *pBuffer)

The type of a callback function which receives monitor information from the RIP for the current job.

Parameters

	cbBuffer	The length of the monitor information data in pBuffer.
[in]	pBuffer	A buffer of text to output to the monitor information channel.

Text is streamed, so error messages and so on may span more than one call. This type is used by SwLeStart() and SwLeSetMonitorFunction().

◆ SwLeParamCallback

typedef int32() SwLeParamCallback(void *pJobContext, const void *param)

The type of callback functions triggered when a parameter is changed.

Callback functions may be registered against some parameter sets, to monitor changes to their values. This is often used to select the backend behavior when the PageBufferType pagebuffer parameter is changed. The skin should respond by calling SwLeSetRasterAPI() with appropriate callback functions for the selected backend.

Parameters

pJobContext	An opaque pointer to caller-managed data, as originally provided by SwLeJobStart() or inputq_print_job().
param	A generic pointer, either pointing to an integer, a float, a boolean (integer), or a NUL-terminated string containing the new value of the pagebuffer parameter. The value pointed to should not be changed.

Returns: One of the Param* enumeration values from swdevice.h.

Note: This callback deliberately does not expose the name or type of the parameter. Individual callbacks should be registered for each parameter of interest, and the function used to register the callback should verify the type of callback via a separate parameter.

◆ SwLeRIPEXITCALLBACK

typedef void() SwLeRIPEXITCALLBACK(int32 errorCode, const uint8 *pszText)

The type of a callback function which is called when the RIP exits. Used in SwLeSetRipExitFunction().

Parameters

errorCode	An error code indicating the reason that the RIP exited. This will be zero if the RIP exited normally.
pszText	A zero-terminated string describing the reason for a RIP exit. This will be `NULL` if the RIP exited normally.

Enumeration Type Documentation

◆ SwLeProcessOp

enum SwLeProcessOp

Operations for SwLeDo().

This enumeration describes the operations that can be requested using SwLeDo(). The SwLeDo() call performs all of the operations to move the SDK and RIP between the current state and the desired state. There are some internal SDK states that are not explicit here.

There will be at least two calls to SwLeDo(), and usually three or more, in any RIP integration:

A call to start up the RIP. This will usually request SW_LE_DO_SDK_START, because this is an appropriate point to set raster callback functions, register APIs and instances of APIs (e.g., devices, tiling methods, etc).
One or more calls to process input jobs. This is done by requesting SW_LE_DO_PROCESS_QUEUE. The RIP will be started up if necessary, and all jobs will be processed from the input queue, waiting until there are no more input sources available. Repeated calls can be made to process input jobs. The RIP will normally continue running between calls to SwLeDo() with SW_LE_DO_PROCESS_QUEUE. If a quit job is sent to the RIP to force a hard reboot, it will be restarted automatically on the next call with SW_LE_DO_PROCESS_QUEUE.
A call to shutdown the RIP and SDK, by requesting SW_LE_DO_SHUTDOWN.

Other intermediate states may be requested during startup or shutdown, if there is a need to intervene at a particular point in the SDK or RIP lifecycle.

The entire SDK may be started up and shutdown multiple times during the lifetime of the host process. Each shutdown is managed by requesting SW_LE_DO_SHUTDOWN, and then restarting in the normal way. If shutting the entire SDK down, all raster callback functions, monitor functions, API pointers, etc., must be re-installed each time. The memory limits used by the SDK and RIP may be changed for each restart.

The RIP may be started up and shutdown multiple times without terminating the SDK, by requesting SW_LE_DO_RIP_START to start up and SW_LE_DO_RIP_STOP to shutdown. If the RIP is restarted after shutdown in this manner the RIP callback functions and API pointers do not need to be re-installed. Shutting down and restarting the RIP in this manner allows the host process to recover and use the memory that the RIP uses during periods that the RIP is not in active use.

Enumerator
SW_LE_DO_INITRUNTIME	Initialise the SDK runtime. The SDK will initialise its static data. This call can often be combined with starting the SDK, by calling SwLeDo() with operation SW_LE_DO_SDK_START. The main reason to call it separately is that a default monitor callback can be set immediately after this call to intercept messages from SDK startup and shutdown, by calling SwLeSetMonitorFunction(). Requesting this state ensures that SwLeInitRuntime() has been called. The next call should be a request for a subsequent state using SwLeDo(), or SwLeShutdown() for a manual shutdown.
SW_LE_DO_SDK_START	Start the SDK runtime. The SDK will allocate the memory arena (reserving the address space requested) and a memory pool for the SDK allocations, and will allocate a thread pool for timers, but the bulk of the memory and thread resources required for running the RIP will not be allocated in this state. The RDR and event system, timers, timeline, input queue, and hotfolder system will be started in this state. If the SDK is compiled as a DLL, then the RDR pointer used by the SDK can be acquired for use by the application layer after reaching this state, and it can then be used to acquire pointers to the other APIs provided by the SDK. This state is suitable for registering raster callbacks, event handlers, and device instances, especially those that may be needed during RIP bootup (e.g., a %preboot% device, overriding the filesystem device, or any other OEM specific integration devices), and other integration-specific API implementations. Requesting this state ensures that SwLeInitRuntime() and SwLeSDKStart() have been called. The next call should be a request for a subsequent state using SwLeDo(), or SwLeSDKEnd() and then SwLeShutdown() for a manual shutdown.
SW_LE_DO_RIP_MEMINIT	Initialise the RIP memory system, but do not start the interpreter. This state can be requested if the application wishes to make memory allocations in the RIP's memory pools using SwAlloc(), or interact with APIs hosted in the RIP. Allocations from the RIP's memory pools will be counted against the reserved RIP memory, and will affect when the RIP performs low-memory operations. There is no point requesting this state if the application is not going to perform operations that require allocation from RIP memory. Requesting this state ensures that SwLeMemInit() has been called. The next call should be a request for a subsequent state using SwLeDo(), or SwLeStart() for a manual RIP start. Note Most of the APIs that require registration of callbacks in the RIP core are migrating to use RDR instead, so the need to request this state is expected to disappear in future. The color management module (CMM) and halftone module (HTM) APIs currently require instances registering in this state.
SW_LE_DO_RIP_START	Start the RIP interpreter. In this state, the interpreter is started and is ready for processing jobs. Requesting this state ensures that SwLeStart() has been called. The next call should be a request for a subsequent state using SwLeDo(), SwLeProcessInputQueue() or SwLeProcessJobs() to process jobs from the input queue, or SwLeStop() for a manual RIP shutdown (followed by SwLeSDKEnd() and SwLeShutdown() if shutting down the SDK as well).
SW_LE_DO_PROCESS_QUEUE	Process all of the jobs currently in the input queue. Requesting this state calls SwLeProcessJobs(). This uses SwLeProcessInputQueue() to process one job at a time until there are no jobs left in the input queue, or a job reported an error, or the RIP quits in response to a job stopping it. If the RIP quit in response to a job stop, the next call should be a request for a subsequent state using SwLeDo(), or SwLeStop() for a manual RIP shutdown (followed by SwLeSDKEnd() and SwLeShutdown() if shutting down the SDK as well). If a job reported an error, the next call may either be another call to SwLeDo() with this state to continue processing jobs, a request for a subsequent state using SwLeDo(), or SwLeStop() for a manual RIP shutdown (followed by SwLeSDKEnd() and SwLeShutdown() if shutting down the SDK as well). The reason that a job failed may be extracted by monitoring RIP operation using error events, monitor event UIDs, and timeline events. If the function returned because the input queue was empty, the caller may choose to add more jobs to the input queue and call SwLeDo() with this operation again, the caller may block waiting for more asynchronous input by calling inputq_wait(), or the caller may shut down the RIP using a request for a subsequent state using SwLeDo(), or SwLeStop() for a manual RIP shutdown (followed by SwLeSDKEnd() and SwLeShutdown() if shutting down the SDK as well). If the SwLeDoParams::fProcessQueueWait boolean is `TRUE`, and there are persistent sources of input registered with the inputs API, this call to SwLeDo() will block in inputq_wait() until more input arrives, or the input sources are deregistered.
SW_LE_DO_RIP_STOP	Stop the RIP interpreter and threads. Requesting this state ensures that SwLeStop() has been called. The RIP's memory and thread resources are released. Any allocations made from the RIP's memory system should be freed using SwFree() before this call, or references to memory allocated should be forgotten (the memory will be recovered by this call). The next call should be a request to shutdown the SDK by calling SwLeDo() with a subsequent operation, a request to restart the RIP by calling SwLeDo() with SW_LE_DO_RIP_MEMINIT or SW_LE_DO_RIP_START, or SwLeSDKEnd() and SwLeShutdown() to manually shut down the SDK.
SW_LE_DO_SHUTDOWN	Shut down the SDK. The SDK will release its memory arena and all remaining resources. If compiled as a DLL, the SDK DLL and core library DLL may be unloaded if desired. Requesting this state ensures that SwLeSDKEnd() and SwLeShutdown() have been called. If there were no fatal errors, the SDK may be reinitialised by calling SwLeDo() to request any of the previous states. Memory parameters to the RIP may be changed by requesting this state, updating the memory request sizes in SwLeDoParams, and restarting the RIP. Thie operation can be called from any state, including when SwLeInitRuntime() has never been called or if SwLeShutdown() has already been called. This makes it easy to shut down the SDK in exceptional conditions.

◆ SwLeProcessQueueResult

enum SwLeProcessQueueResult

Return values for SwLeProcessInputQueue() and SwLeProcessJobs().

Enumerator
SW_LE_QUEUE_EMPTY	There was nothing in the queue.
SW_LE_QUEUE_JOB_OK	Ran one job from the queue with no errors.
SW_LE_QUEUE_JOB_ERROR	Ran one job from the queue but job failed.
SW_LE_QUEUE_NO_RIP	RIP never booted or has previously exited.

Function Documentation

◆ GetDataAPI()

struct sw_data_api* GetDataAPI ( void )

Get and cache the data API pointer.

Returns: A pointer to data API version 20181206 or later, or NULL if it is overridden or not preset. Harlequin 13 and later have this API built in.

◆ KSetSystemErrorLevel()

HqBool KSetSystemErrorLevel ( int32 errlevel )

Set system error record level.

Parameters

errlevel Request level: 0 - no record; 1 - record errors except file/path not found. 2 - record all errors.

Returns: TRUE if fLevel is valid; FALSE otherwise.

◆ PKRecordSystemError()

void PKRecordSystemError	(	int32	errcode,
		int32	errline,
		const char *	pErrfile,
		HqBool	fSysErr
	)

Record through the monitor callback system errors according to the error level set by KSetSystemErrorLevel().

Note that the error will not be recorded if no monitor callback has been supplied.

Parameters

errcode	Error code from the failed operation.
errline	Line number where error occurred. Use the `__LINE__` macro, as per an assertion failure.
pErrfile	Source file where the error occurred. Use the `__FILE__` macro, as per an assertion failure.
fSysErr	Indicates whether the error code corresponds to an error specified by the operating system. If this is `TRUE`, the implementation will use platform-specific code to transform errcode into a human-readable string. (This can be done with `FormatMessage()` on Windows, and `strerror()` on Unix-based platforms, for example). If this argument is `FALSE`, only the numeric error code will be reported.

◆ SkinDynamicBufferAdd()

HqBool SkinDynamicBufferAdd	(	SkinDynamicBuffer *	buffer,
		const char *	format,
			...
	)

Helper function to write formatted string (using swncopyf()) to the end of a dynamic buffer, extending the buffer as necessary.

Parameters

buffer	A pointer to an initialised dynamic buffer structure.
format	A swcopyf() format, followed by the appropriate variable args.

Return values

TRUE	If the formatted string was written to the buffer successfully. The buffer's data field may have been re-allocated.
FALSE	If the buffer could not be written or extended. The buffer's data field has been freed, and the buffer is cleared in this case.

Note: It is the caller's responsibility to free the buffer's data field using SkinDynamicBufferFree() after use.

◆ SkinDynamicBufferFree()

void SkinDynamicBufferFree ( SkinDynamicBuffer * buffer )

Free any memory allocated for dynamic buffer data.

Parameters

buffer A pointer to an initialised dynamic buffer structure.

Note this does not free the memory pointed to by buffer, but the buffer's data field within it.

◆ SkinDynamicBufferReset()

void SkinDynamicBufferReset ( SkinDynamicBuffer * buffer )

Reset a dynamic buffer to contain no data, but preserve the existing allocated memory.

Parameters

buffer A pointer to an initialised dynamic buffer structure.

◆ SwLeAddCustomDevices()

HqBool SwLeAddCustomDevices	(	int32	nCustomDevices,
		DEVICETYPE **	ppCustomDevices
	)

Makes DEVICETYPE objects available for discovery by the RIP.

This call is optional. It may be called more than once before SwLeStart() to make additional DEVICETYPE available to the the RIP. This function registers the device types in RDR, under the class RDR_CLASS_DEVICETYPE, the device number for the RDR type, and zero for the RDR ID. Device types can be registered directly in RDR as an alternative to calling this function.

Parameters

nCustomDevices	The number of DEVICETYPEs to add.
ppCustomDevices	Pointer to array of DEVICETYPEs to be add.

Return values

TRUE	All devices were added successfully.
FALSE	One or more devices could not be added.

◆ SwLeDo()

int32 SwLeDo	(	int32	op,
		SwLeDoParams *	params
	)

Perform required operations to reach the requested SDK and RIP state.

Parameters

[in]	op	The operation requested to change the SDK and RIP state. This is one of the SwLeProcessOp enumeration values.
[in]	params	A structure containing the memory parameters to initialize the RIP, callback functions for monitor output.

Returns: An exit status of the RIP or SDK processes. This is zero for success, non-zero for a fatal error. Note that success does not mean that jobs were processed without errors being trapped: error information for jobs should be monitored and extracted using error events, monitor event UIDs, and timeline events.

◆ SwLeExitCode()

int32 SwLeExitCode ( void )

Returns the exit status of the RIP.

The exit status is only valid after the RIP thread terminates (i.e., after return from the SwLeStop() function). It is zero if the RIP terminated cleanly, non-zero otherwise.

◆ SwLeInitRuntime()

HqBool SwLeInitRuntime ( void * pContext )

Initializes skinkit variables prior to starting the RIP.

This function is normally called from SwLeDo().

This function must be called before each attempt to start or restart the RIP. It initialises or re-initialises variables which skinkit code expects to have known initial values.

Parameters

pContext Currently unused - clients should pass NULL.

Returns: Currently always returns TRUE.

Note: The preferred way to control the Harlequin SDK and RIP is to call SwLeDo(). SwLeDo() will call this function in the correct sequence, as necessary. If not using SwLeDo(), this should be the first SDK control function called by the skin.

◆ SwLeInJob()

HqBool SwLeInJob ( void )

Low-level function to indicate if the skin is within a job.

It is not usually necessary to call this function directly.

Returns TRUE if SwLeJobStart() has been called and the matching SwLeJobEnd() has not yet been called.

Return values

TRUE	if a job is in progress;
FALSE	otherwise.

◆ SwLeJobEnd()

HqBool SwLeJobEnd ( void )

Low-level function to terminate the current job.

It is not usually necessary to call this function directly. The SwLeProcessInputQueue() function will call this for you.

It will return FALSE if SwLeJobStart() has not been called first.

Return values

TRUE	on success;
FALSE	otherwise.

◆ SwLeJobStart()

HqBool SwLeJobStart	(	uint32	cbBuffer,
		uint8 *	pBuffer,
		void *	pJobContext
	)

Low-level function to prepare the Harlequin RIP to receive a PostScript language job.

It is not usually necessary to call this function directly. The SwLeProcessInputQueue() function will call this for you.

This function must be called before feeding any job data to the RIP. It must be called after booting the RIP using SwLeStart(). It must not be called while a job is in progress, and returns FALSE if that happens.

Parameters

cbBuffer	The number of characters in the (not necessarily nul-terminated) string pBuffer.
pBuffer	A pointer to the "config job": a PostScript language fragment which is run at save level 0 to set the correct environment for the job, or `NULL`. This argument can be `NULL`, in which case cbBuffer should be zero.
pJobContext	An arbitrary pointer to caller-managed data. This will be passed as the first argument to the raster data callback and other callbacks during execution of the job.

Return values

TRUE	If the job was started successfully. In this case, SwLeJobEnd() must be called after the job data has been presented to the RIP, even if a subsequent SwLePs() call returns an error.
FALSE	If the job was not started successfully. The application may call SwLeJobStart() again, with corrected configuration data, or may terminate with an error.

(Internally, this call causes bytesavailable to be set on the config device, which will then cause a read on the config device. The pBuffer contents should prepare the /setrealdevice procedure to be run at save level 1, and then supply an open file object for the input job and an open file object for the output stream.)

The configuration job in pBuffer should finish with either two filestreams and true on the PostScript stack, or false on the stack. If the top of the stack is true, the file objects will be used as the standard input and standard output for a PostScript job. When directly injecting a job using SwLePs(), the SDK uses the %console% device mounted for device type CONFIG_DEVICE_TYPE:

(%console%) dup (r) file exch (w) file true

If the top of the stack is false, the server loop will be repeated. This allows jobs containing nothing but enquiry code or configuration data to be run.

◆ SwLeMemInit()

void SwLeMemInit	(	size_t	RIP_maxAddressSpaceInBytes,
		size_t	RIP_workingSizeInBytes,
		size_t	RIP_emergencySizeInBytes,
		void *	pMemory
	)

Pre-initializes the RIP, giving it the memory arena prepared by SwLeSDKStart().

This function is normally called from SwLeDo().

This call is optional, the alternative being to call SwLeStart() directly. However this function must be called if RIP callbacks or modules must be registered before the RIP is fully booted by SwLeStart(). If this call is made, it must be after SwLeSDKStart().

Parameters

RIP_maxAddressSpaceInBytes	Size of virtual memory available to RIP, as returned by SwLeSDKStart().
RIP_workingSizeInBytes	Size of the memory buffer that the RIP will work in, as returned by SwLeSDKStart().
RIP_emergencySizeInBytes	Additional memory beyond RIP_workingSizeInBytes to use before resorting to partial paint. Only meaningful if pMemory is `NULL`.
pMemory	A pointer to an allocated buffer of size RIP_workingSizeInBytes, or `NULL`. If it is `NULL`, the skin allocates RIP_workingSizeInBytes bytes of memory itself.

◆ SwLeProcessingError()

HqBool SwLeProcessingError ( void )

Low-level function to indicate whether an error occurred in the most recent chunk of job data that was processed by the RIP.

It is not usually necessary to call this function directly.

The return values from SwLePs() and SwLeJobEnd() are probably a more convenient means of error detection.

Return values

TRUE	if an error was signalled by the RIP;
FALSE	otherwise.

◆ SwLeProcessInputQueue()

int32 SwLeProcessInputQueue ( void )

Process a job from the skin's input queue implementation.

This function performs the inner part of the job processing loop SwLeProcessJobs(). It calls SwLeSetJobNumber(), SwLeSetJobName(), SwLeJobStart() and SwLeJobEnd() with a setup appropriate to detect the type and interpret a job specified by the first input queue entry. This function does not block on the input queue; if there are no entries on the input queue, it returns SW_LE_QUEUE_EMPTY.

Returns: One of the SwLeProcessQueueResult enumeration values.

See also: Input queue and source API.

◆ SwLeProcessJobs()

int32 SwLeProcessJobs ( SwLeDoParams * params )

Process jobs from the input queue using SwLeProcessInputQueue() until there are no more jobs and (optionally) no more input sources.

Parameters

[in] params A pointer to structure containing parameters that affect processing. If this pointer is NULL, then the default is to continue after errors in jobs and to wait for more queue input after processing jobs.

Returns: One of the SwLeProcessQueueResult enumeration values. The value SW_LE_QUEUE_JOB_OK will not be returned, because this function will continue looking for jobs from the input queue. If the SwLeDoParams::fContinueAfterError parameter is TRUE, then SW_LE_QUEUE_JOB_ERROR will not be returned either.

The SwLeDoParams::fContinueAfterError boolean indicates if this function should continue processing more jobs if a job fails to complete because of an error. This is normally set to TRUE when operating the RIP as a server process.

The SwLeDoParams::fProcessQueueWait boolean indicates if this function should wait for more input after processing jobs, if there are persistent sources of input that could add more jobs. This is normally set to TRUE when operating the RIP as a server process, blocking the caller until more input arrives or the input sources are deregistered. If you want to process jobs by polling the RIP, set this parameter to FALSE, and the client can loop around adding jobs to the input queue and then processing them in batches by calling SwLeProcessJobs(), or calling SwLeDo() with the SW_LE_DO_PROCESS_QUEUE operation.

See also: Input queue and source API.

◆ SwLePs()

HqBool SwLePs	(	uint32	cbBuffer,
		uint8 *	pBuffer
	)

Low-level function to pass a chunk of PostScript language data to the Harlequin RIP.

It is not usually necessary to call this function directly.

This function can be called repeatedly to pass an entire PostScript job to the RIP in chunks, if directly injecting a job.

It is normally not necessary to directly inject PostScript jobs. Global Graphics recommends using the Input queue and source API with the SwLeProcessInputQueue() function to queue and process jobs. SwLeProcessInputQueue() will configure the RIP to detect the type of the job, perform appropriate configuration at the correct save levels, and read the job file directly.

This function will fail and return FALSE unless SwLeJobStart() has been called first.

To make the RIP read directly from a file, use the PostScript fragment shown in the Harlequin RIP Extensions Manual to set stdin. The following is a simple variation on that fragment:

(\<filename\>) (r) file cvx dup
(%stdout%) (w) file
statusdict /setstdio get exec
exec

To run a PDF file, use a PostScript language fragment to call the Harlequin RIP extension operator pdfexec on an opened file.

In the event of an unstopped PostScript language error or other abnormal event, the function will return FALSE. The caller should call SwLeJobEnd() after detecting an error.

(Internally, this returns the buffer contents to the read calls on %console%, perhaps in chunks if bigger than the read buffer the RIP supplies, and on completion waits for the next read call or close call before returning. Errors are detected by an unexpected call to close on %console%. While waiting for these events various callbacks may also be requested of the function.)

When using Harlequin Parallel Pages, SwLePs() will return when the interpreter has accepted all of the input. This return may be before all of the pages in a job have been rendered. It is possible that a page may encounter a render error after SwLePs() returns successfully. A subsequent call to SwLePs() or SwLeJobEnd() will return this error. If the skin needs to wait until pages are rendered for each buffer of data it should provide its own synchronisation between the render callbacks and the SwLePs() calls.

The preferred method to terminate the RIP is to call SwLeStop() between jobs.

Parameters

cbBuffer	The length, in bytes, of the PostScript buffer pBuffer submitted to the RIP.
pBuffer	The PostScript buffer to submit to the RIP.

Return values

TRUE	if the PostScript was processed without error;
FALSE	otherwise. The caller must use SwLeJobEnd() to complete the job, regardless of error status.

◆ SwLeSDKEnd()

void SwLeSDKEnd ( int32 exitCode )

Shutdown the SDK support libraries.

This function is normally called from SwLeDo().

This call is required if SwLeSDKStart() succeeds. It should be called before SwLeShutdown(), before exiting the application. The RIP may be re-started without shutting down the SDK libraries if it can share the same memory configuration. If the memory configuration is to be changed, SwLeSDKEnd() and SwLeSDKStart() must be called again before restarting the RIP.

Parameters

exitCode Indicates whether the application is shutting down in an error state. The argument should be the return value from SwLeStop(). It will be zero if the RIP shut down successfully, non-zero if the application is to indicate an error state.

◆ SwLeSDKStart()

HqBool SwLeSDKStart	(	size_t *	RIP_maxAddressSpaceInBytes,
		size_t *	RIP_workingSizeInBytes,
		void *	pMemory,
		SysMemFns *	pSysMemFns,
		uint8 **	reasonText
	)

Initialise SDK support libraries for the RIP.

This function is normally called from SwLeDo().

The RIP relies upon several support libraries to operate. The MPS (Memory Pool System) is used for memory management. RDR provides for decoupled discovery, overriding, and priority management of resources. Events provides an observer interface with prioritisation and filtering. Timelines provides lifespan communication, progress and contextualisation. Timers provide timed callbacks.

These support libraries are initialised and finalised separately from the RIP because they provide functions generally useful for the RIP skin, they allow modules to be prepared for use by the RIP, they allow configuration of libraries that the RIP uses before RIP startup. The lifetime of the support libraries may exceed one RIP instantiation.

The core RIP and the skin share the same memory arena. However, the skin will have its own pool within that arena. This call starts by creating the MPS memory arena and the skin's MPS memory pool. It is possible to apply a constraint to the amount of address space and memory that the core RIP and the skin are permitted to use in combination. Use the RIP_maxAddressSpaceInBytes parameter to limit address space and RIP_workingSizeInBytes parameter to limit memory committed. The working space size will be limited to the maximum address space allowed.

It is also possible for the RIP to work within a region of memory that has been pre-allocated by the host application. In this case, the pMemory parameter should point to the memory region, and the RIP_workingSizeInBytes parameter should indicate the memory block size.

This function must be called after SwLeInitRuntime(), but before booting the RIP (i.e., SwLeMemInit() or SwLeStart()), and before any use of the other skin memory-management functions defined in file mem.h are called.

Parameters

[in,out]	RIP_maxAddressSpaceInBytes	A pointer to the size of the maximum address space the RIP can use, measured in bytes. If the value referenced is zero on entry, the RIP will set a size based on the address space available on the operating system and the working space size. You may want to adjust this if you link large libraries into the RIP executable. On a successful exit, the value is set to the actual size of address space reserved for the RIP.
[in,out]	RIP_workingSizeInBytes	A pointer to the size of working memory permitted for the RIP, measured in bytes. If the value referenced is zero on entry, the RIP will calculate a default size suitable for testing the RIP running as the sole application using all the memory resources of the machine. On a successful exit, the value is set to the actual size of working memory applied for the RIP.
[in]	pMemory	Points to a caller-allocated memory block that the RIP should use. If this is non-`NULL`, the RIP will work within this memory block, rather than allocating its own memory. The size of the block is defined by RIP_workingSizeInBytes, which must not be zero. If this pointer is `NULL`, then the RIP will allocate and manage its own memory, suitably constrained by RIP_maxAddressSpaceInBytes and RIP_workingSizeInBytes.
[in]	pSysMemFns	Points to a structure providing the suite of system memory handling functions for use by SysAlloc() and SysFree(). If this is `NULL` the default functions are used, which are implemented using the OS malloc() and free(). These allocation functions are used by the skin's example raster handlers for large allocations that should not be included in the MPS arena or constrained by RIP_workingSizeInBytes.

Deprecated:

Parameters

[out] reasonText An optional pointer to receive failure reasons. If non-NULL, this will be set to the reason that this function failed, or NULL if this function succeeded. This parameter is deprecated, the callback set by SwLeSetRipExitFunction() can be used to capture failure reasons for SDK control function failures up to and including running the RIP.

Return values

TRUE	The SDK initialisation succeeded. In this case, RIP_maxAddressSpaceInBytes is set to size of the maximum address space the RIP can use, RIP_workingSizeInBytes is set to the actual size of working memory the RIP will use, and reasonText is set to `NULL`.
FALSE	The SDK initialisation failed.

Note: This function must be called after SwLeInitRuntime(), and before SwLeMemInit() or SwLeStart(). If this function succeeds, the caller should call SwLeSDKEnd() before ending the application. The RIP may be re-started without shutting down the SDK libraries if it can share the same memory configuration. If the memory configuration is to be changed, SwLeSDKEnd() and SwLeSDKStart() must be called again before restarting the RIP.

◆ SwLeSetHqAssertHandlers()

void SwLeSetHqAssertHandlers ( HqAssertHandlers_t * handlers )

Set the HQASSERT() and HQTRACE() handler functions to be used by the Skin, SDK and the RIP.

Parameters

[in] handlers The handlers to be used by the SDK and the RIP. If this structure pointer is NULL, the assert and trace handlers will be reset to their default values for the SDK. If this pointer is non-NULL, but one or more of the handler pointers is NULL, then only the non-NULL handlers will be overridden.

This function must be used to install custom handlers if the RIP is linked as a dynamic library, so that the library installs the desired handler functions. This function must be called before SwLeStart().

◆ SwLeSetJobName()

HqBool SwLeSetJobName	(	const uint8 *	name,
		size_t	namelen
	)

Low-level function to set the job name used by the next job invoked by SwLeJobStart().

It is not usually necessary to call this function directly. The SwLeProcessInputQueue() function will call this for you.

Parameters

[in]	name	The name to set for the next job. This may be `NULL` if namelen is zero. The job name is copied from this memory, so it can be an auto-scoped variable.
[in]	namelen	The length of the name. If this is non-zero

Return values

FALSE	Returned if there was a parameter error, or the job name could not bt set because of a failure to allocate memory. The previous job name will be cleared to empty.
TRUE	The job name was set as requested.

The job name is used as the title on the SWTLT_SKIN_JOB timeline. A new job name must be set before each call to SwLeJobStart(). The skin job timeline title will be empty if no job name was explicitly set.

◆ SwLeSetJobNumber()

void SwLeSetJobNumber ( int32 jobno )

Low-level function to set the job number used by the next job invoked by SwLeJobStart().

It is not usually necessary to call this function directly. The SwLeProcessInputQueue() function will call this for you.

Parameters

jobno The next job number to use.

The job number is attached to the SWTLT_SKIN_JOB timeline as a context with identifier SW_SKIN_JOB_NUMBER_CTXT. The job number starts at zero for each new RIP invocation. If the job number is set to a non-zero value, it will automatically increment unless reset before each job. This allows a series of configuration jobs to be run by the RIP with number 0, and then real jobs to be given explicit numbers or automatically numbered by calling this function after SwLeStart().

◆ SwLeSetRipExitFunction()

void SwLeSetRipExitFunction ( SwLeRIPEXITCALLBACK * pfnRipExit )

Supply a callback function to be called when the RIP exits.

Calling this function is optional. If it is called, it should be after the first SwLeDo() or SwLeInitRuntime(). Initialising the SDK runtime will reset the RIP exit callback function.

Parameters

pfnRipExit Function which is to be called whenever the RIP exits.

◆ SwLeSetRipRebootFunction()

void SwLeSetRipRebootFunction ( SwLeRIPREBOOTCALLBACK * pfnRipReboot )

Supply a callback function to be called when the RIP reboots.

Calling this function is optional. If it is called, it should be after the first SwLeDo() or SwLeInitRuntime(). Initialising the SDK runtime will reset the RIP reboot callback function.

Parameters

pfnRipReboot Function which is to be called whenever the RIP reboots.

◆ SwLeSetRipRendererThreads()

void SwLeSetRipRendererThreads ( int32 nThreads )

Sets the number of renderer threads.

It is optional to call this function. If called, it must be before the first call to SwLeMemInit() or SwLeStart() for a RIP instantiation.

Parameters

nThreads The number of threads usable by the RIP.

◆ SwLeShutdown()

void SwLeShutdown ( void )

Performs shutdown operations when the application exits.

This function is normally called from SwLeDo().

This function must be called after the RIP and the SDK have been shutdown for the last time, before the application exits.

◆ SwLeStart()

HqBool SwLeStart	(	size_t	RIP_maxAddressSpaceInBytes,
		size_t	RIP_workingSizeInBytes,
		size_t	RIP_emergencySizeInBytes,
		void *	pMemory,
		SwLeMONITORCALLBACK *	pfnMonitor
	)

Starts the Harlequin RIP, giving it the memory arena prepared by SwLeSDKStart().

This function is normally called from SwLeDo().

Text strings which the RIP outputs (error messages, information messages, and jobs writing to stdout and stderr) are delivered to the callback function supplied in the parameter pfnMonitor (when not NULL) for the duration of the RIP session.

In response to this call, the skin starts a thread which calls the core RIP interface function SwStart(), passing it the memory and the device types defined in the skin. On completion (that is, the first downward call for more data, namely bytesavailable on the %config% device) this function returns in its own thread.

Parameters

RIP_maxAddressSpaceInBytes	Size of virtual memory available to RIP, as returned by SwLeSDKStart().
RIP_workingSizeInBytes	Size of the memory buffer that the RIP will work in, as returned by SwLeSDKStart().
RIP_emergencySizeInBytes	Additional memory beyond RIP_workingSizeInBytes to use before resorting to partial paint. Only meaningful if pMemory is `NULL`.
pMemory	A pointer to an allocated buffer of size RIP_workingSizeInBytes, or `NULL`. If it is `NULL`, the skin allocates RIP_workingSizeInBytes bytes of memory itself.
pfnMonitor	A pointer to a monitor callback function which the skin must implement if it wishes to receive monitor information from the RIP. This argument can be `NULL`, in which case monitor information will be sent to the SDK's default handler, installed with SwLeSetMonitorFunction(). If no SDK default handler has been installed, then no monitor information will be sent to the skin.

Return values

TRUE	The RIP started successfully.
FALSE	The RIP did not start successfully.

◆ SwLeStop()

int32 SwLeStop ( void )

Request that the RIP shutdown.

This function is normally called from SwLeDo().

This function should only be called in between job boundaries. It submits a shutdown PS job to the RIP, then waits for the RIP to exit.

Returns: The exit status of the RIP. This will be zero if the RIP shutdown cleanly, non-zero otherwise. The value returned should be passed to SwLeSDKEnd().

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Control flow functions

Input queue job processing functions

Low-level job processing functions

Utility functions

Macro Definition Documentation

◆ SW_LE_STOP_PS

Typedef Documentation

◆ SkinDynamicBuffer

◆ SwLeMONITORCALLBACK

◆ SwLeParamCallback

◆ SwLeRIPEXITCALLBACK

Enumeration Type Documentation

◆ SwLeProcessOp

◆ SwLeProcessQueueResult

Function Documentation

◆ GetDataAPI()

◆ KSetSystemErrorLevel()

◆ PKRecordSystemError()

◆ SkinDynamicBufferAdd()

◆ SkinDynamicBufferFree()

◆ SkinDynamicBufferReset()

◆ SwLeAddCustomDevices()

◆ SwLeDo()

◆ SwLeExitCode()

◆ SwLeInitRuntime()

◆ SwLeInJob()

◆ SwLeJobEnd()

◆ SwLeJobStart()

◆ SwLeMemInit()

◆ SwLeProcessingError()

◆ SwLeProcessInputQueue()

◆ SwLeProcessJobs()

◆ SwLePs()

◆ SwLeSDKEnd()

◆ SwLeSDKStart()

◆ SwLeSetHqAssertHandlers()

◆ SwLeSetJobName()

◆ SwLeSetJobNumber()

◆ SwLeSetRipExitFunction()

◆ SwLeSetRipRebootFunction()

◆ SwLeSetRipRendererThreads()

◆ SwLeShutdown()

◆ SwLeStart()

◆ SwLeStop()