|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
The input queue and source API. More...
Files | |
| file | inputsapi.h |
| Header file defining the Input queue and source API. | |
| file | inputserrors.h |
| Header file defining the Input queue and source API result translation. | |
Data Structures | |
| struct | sw_inputq_setup |
| Name and contents of a RIP configuration. More... | |
| struct | sw_inputq_api_20171010 |
| Input queue controller function pointer API version 20171010. More... | |
| struct | SWMSG_INPUTQ_CHANGE |
| The message associated with SWEVT_INPUTQ_CHANGE events. More... | |
| struct | SWMSG_INPUTS_ENABLE |
| The message associated with SWEVT_INPUTS_ENABLE events. More... | |
Macros | |
| #define | inputq_print_job inputq_api->print_job |
| Insert a job into the input queue for printing by the RIP. More... | |
| #define | inputq_delete_job inputq_api->delete_job |
| Delete a job from the input queue. More... | |
| #define | inputq_iterate_setups inputq_api->iterate_setups |
| Iterate over the available job setups. More... | |
| #define | inputq_source_add inputq_api->source_add |
| Inform the input queue system of a persistent source that will add entries to the queue. More... | |
| #define | inputq_source_remove inputq_api->source_remove |
| Inform the input queue system that a persistent source previously added with the sw_inputq_api_20171010::source_add() method has been removed. More... | |
| #define | inputq_signal_waiters inputq_api->signal_waiters |
| Release threads blocked on the input queue, even if there is no input. More... | |
Typedefs | |
| typedef HqnResult | sw_inputq_result |
| Status return type for API calls. More... | |
| typedef struct sw_inputq_setup | sw_inputq_setup |
| Name and contents of a RIP configuration. More... | |
| typedef sw_inputq_result() | sw_inputq_setup_fn(const sw_inputq_setup *setup, size_t size, void *data) |
| Type of a callback function for iterating RIP configurations. More... | |
| typedef void() | sw_inputq_decontext_fn(void *jobcontext) |
| Type of a callback function for disposing of a job context. More... | |
| typedef HqBool() | sw_inputq_mkcontext_fn(void *data, void **jobcontext, sw_inputq_decontext_fn **decontext) |
| Type of a callback function for making a job context and its disposal callback. More... | |
| typedef struct sw_inputq_api_20171010 | sw_inputq_api_20171010 |
| Input queue controller function pointer API version 20171010. | |
| typedef int32 | sw_inputq_change_reason |
| Type for queue change reasons. Variables of this type should store one of the SW_INPUTQ_CHANGE_REASON enumeration values. | |
| typedef struct SWMSG_INPUTQ_CHANGE | SWMSG_INPUTQ_CHANGE |
| The message associated with SWEVT_INPUTQ_CHANGE events. More... | |
| typedef int32 | sw_input_enable_state |
| Type for input enable states. Variables of this type should store one of the SW_INPUT_ENABLE_STATE enumeration values. | |
| typedef struct SWMSG_INPUTS_ENABLE | SWMSG_INPUTS_ENABLE |
| The message associated with SWEVT_INPUTS_ENABLE events. More... | |
Enumerations | |
| enum | SW_INPUTQ_RESULT { SW_INPUTQ_SUCCESS = HQN_RESULT_SUCCESS , SW_INPUTQ_ERROR , SW_INPUTQ_ERROR_MEMORY , SW_INPUTQ_ERROR_SETUP , SW_INPUTQ_ERROR_JOB , SW_INPUTQ_ERROR_QPOS , SW_INPUTQ_ERROR_PARAMS } |
| Return codes for API calls. More... | |
| enum | SW_INPUTQ_CHANGE_REASON { SW_INPUTQ_JOB_ADDED_Q , SW_INPUTQ_JOB_ADDED , SW_INPUTQ_JOB_DELETED_UI , SW_INPUTQ_JOB_DELETED_API , SW_INPUTQ_JOB_DELETED_AUTO , SW_INPUTQ_JOB_DELETED_Q } |
| Reasons for queue change event message. More... | |
| enum | SW_INPUT_ENABLE_STATE { SW_INPUTS_ENABLE_UNKNOWN = -1 , SW_INPUTS_ENABLE_STOPPED = 0 , SW_INPUTS_ENABLE_START = 1 , SW_INPUTS_ENABLE_STOP = 2 } |
| Valid states for the SWMSG_INPUTS_ENABLE::enable field. More... | |
Functions | |
| static HqnResult | inputq_result_translate (sw_inputq_result result) |
| Translate an inputs-specific error code to a generic HqnResult error code. More... | |
The input queue and source API.
The input system is a system for processing incoming jobs. Input methods feed into a queue, from which the RIP processes jobs.
The input queue is implemented in the RIP skin, and jobs are read from it by the config device or job processing loop. The inputs API provider clients are in the RIP skin too: the input sources or plugins. The API provides calls to add print jobs to the queue, monitor the queue state, delete jobs from the queue, query and manage the queue system state, manage input sources, and iterate job setups for use with queued jobs.
The macros inputq_print_job() and inputq_delete_job() are used for direct submission and deletion of jobs. Setups known to the system may be iterable using inputq_iterate_setups(). inputq_source_add() and inputq_source_remove() can be used to add and remove persistent sources of input, allowing clients to wait for jobs to arrive once the queue is empty. inputq_signal_waiters() will wake up any queue reader waiting on jobs to arrive, allowing them to perform other condition test or status checks.
An input queue API pointer must be discovered using RIP Data Resource (RDR) System and assigned to a suitably-named API pointer variable before these macros are used.
The input system has a started/stopping/stopped state that determines if the system will process incoming jobs. Stopping the system will not abort the jobs currently being processed or already in the input queue, but will prevent any new jobs from being added to the input queue. The state of the input queue is managed through the SWEVT_INPUTS_ENABLE event and its associated SWMSG_INPUTS_ENABLE message. This event acts both to request state changes to start or stop processing the input queue, but also as a notification of the current queue state. Any handler registered at a lower priority than SW_EVENT_NORMAL can observe the state of the queue after it is updated, but cannot change the queue state.
The input queue can be monitored using the SWEVT_INPUTQ_CHANGE event and its associated SWMSG_INPUTQ_CHANGE message. All job additions and deletions are notified through this event.
The input system is automatically started when the Harlequin RIP SDK is started. It remains active until the Harlequin RIP SDK is shutdown. Usage and implementation of the input API in the Harlequin RIP SDK are described in sections Inputting data and Harlequin SDK input queue.
The utility function inputq_result_translate() is provided the translate input API error codes to generic HqnResult error codes.
| #define inputq_delete_job inputq_api->delete_job |
Delete a job from the input queue.
| [in] | job_id | The job ID of the job to delete, as returned by the sw_inputq_api_20171010::print_job() method and reported by the SWEVT_INPUTQ_CHANGE event. If this is positive, just that job will be deleted from the queue. If this is negative, then all jobs except the negated job number will be deleted from the queue. If this is zero, all jobs will be deleted from the queue. |
| #define inputq_iterate_setups inputq_api->iterate_setups |
Iterate over the available job setups.
| [in] | callback | A callback function that will be called for each available setup. The callback function should not take substantial time, should not block, and should not call back into the RIP for anything except memory allocation. |
| [in] | data | A data pointer supplied to the callback function. |
| #define inputq_print_job inputq_api->print_job |
Insert a job into the input queue for printing by the RIP.
| [in] | filename | The filename of the job to print. This is a zero-terminated UTF-8 string, in a skin-dependent form. The HMR skin implementation expects this to be a PostScript device and file name. The skinkit SDK implementation will accept a PostScript device and file name, or a platform relative or absolute file name, which it will convert into a PostScript device and file name. |
| [in] | setupname | An optional name of the setup to use when printing the file. This is a zero-terminated UTF-8 string, in a skin-dependent form. The HMR skin implementation expects this to be a page setup name. The skinkit SDK implementation will accept a PostScript device and file name, a platform absolute file name which it will convert into a PostScript device and file name, or a relative name, which it will convert into a PostScript file name relative to the configps% device. |
| [in] | overrideps | An optional pointer to a buffer of PostScript code used to override aspects of the setup configuration. This is a zero terminated buffer of bytes. |
| [in] | where | Position in the queue to add the job, indexed from 0. An index of -1 will append the job to the end of the queue. |
| jobcontext | An opaque pointer supplied by the skin for job context information. | |
| decontext | A pointer to a callback function to dispose of the job context pointer. If non-NULL, this will be called when the queue entry is destroyed, at least after the SWTLT_SKIN_JOB timeline is created. If the job is deleted from the queue without running, this callback will be called when the job is deleted. | |
| [in,out] | job_id | A pointer to the job ID allocated by the RIP skin. This job number will be reported by various events. Job IDs are always positive integers. Job ID 0 is reserved for the initial boot-up job for the RIP. If the value referenced by job_id is zero on entry, the input queue implementation will allocate a job ID. If the value referenced is non-zero on entry, that job ID will be used. Note that if re-using the same job ID, the sw_inputq_api_20171010::delete_job() method cannot distinguish between the different entries, and will delete all entries with that ID, or none, as instructed. Explicitly setting job IDs is not recommended when using the default input methods provided by the RIP SDK (such as hotfolders or command line); explicitly setting job IDs should only be used when the OEM takes full control of all input methods. |
| #define inputq_signal_waiters inputq_api->signal_waiters |
Release threads blocked on the input queue, even if there is no input.
This function can be called to release threads that are blocked on the input queue so they can test if there is any other action they should take (for example, a process interrupt may request a graceful shutdown and may need to unblock waiting threads).
| #define inputq_source_add inputq_api->source_add |
Inform the input queue system of a persistent source that will add entries to the queue.
Adding a persistent input source affects the return value of inputq_wait(). If there are no persistent input methods when inputq_wait() is called, that function will return FALSE to indicate to the caller that no new input will be available. If there are persistent input methods noted when inputq_wait() is called, that function may block until input is available.
| #define inputq_source_remove inputq_api->source_remove |
Inform the input queue system that a persistent source previously added with the sw_inputq_api_20171010::source_add() method has been removed.
Removing a persistent input source affects the return value of inputq_wait(). If there are no persistent input methods when inputq_wait() is called, that function will return FALSE to indicate to the caller that no new input will be available. If there are persistent input methods noted when inputq_wait() is called, that function may block until input is available.
| typedef void() sw_inputq_decontext_fn(void *jobcontext) |
Type of a callback function for disposing of a job context.
| [in] | jobcontext | The context pointer passed to inputq_print_job(). |
When submitting a job to the input queue, the caller may optionally supply a job context pointer and a callback function of this type to dispose of the job context pointer. The context disposal function will be called when the queue entry is deleted. If the job is run (rather than being deleted from the queue without running), the context pointer will be used as the primary context of the SWTLT_SKIN_JOB timeline, and as the job context parameter for SwLeJobStart(). If the job is run, the disposal is guaranteed to be called after the timeline has been created, so clients can reference count the context safely. In the skinkit SDK and HMR implementations of the input queue, this guarantee is strengthened: the disposal function will be called after the job is complete, so the disposal function can free the job context if desired.
| typedef HqBool() sw_inputq_mkcontext_fn(void *data, void **jobcontext, sw_inputq_decontext_fn **decontext) |
Type of a callback function for making a job context and its disposal callback.
| [in] | data | An opaque pointer passed to the job context factory. |
| [out] | jobcontext | A pointer to receive a new job context, for passing to inputq_print_job(). On exit this may be set to NULL, if the skin does not require job contexts. |
| [out] | decontext | A pointer to receive a job context destructor function, for passing to inputq_print_job(). On exit this may be set to NULL, if the skin does not require job contexts, or it has job contexts but they do not require explicit destruction. |
| TRUE | A new job context was constructed successfully, and is ready for passing to inputq_print_job(). If not passed to that function for any reason, the destructor function (if non-NULL) must be called with the job context as its parameter to dispose of the new job context. |
| FALSE | A job context was not created. |
When submitting a job to the input queue, the caller may optionally supply a job context pointer and a callback function to dispose of the context.
This function type is defined for symmetry with the job context destructor. It is not directly used by the functions in this API, but is expected to be used by job factories that submit jobs using the input queue, i.e., hot folders, network input handlers, etc.
The job context created by this function will be used as the primary context on the SWTLT_SKIN_JOB timeline, and also as the job context parameter for SwLeJobStart().
| typedef HqnResult sw_inputq_result |
Status return type for API calls.
This is a subclass of HqnResult that also supports some specific extra error codes generated by the inputs API (declared as the SW_INPUTQ_RESULT enumeration). Before assigning to values of HqnResult type or any of its other subclasses, sw_inputq_result values must be converted to change the API specific values to HQN_RESULT_SUCCESS or a monitor UID error code greater than MON_CLASS_ERROR. This can be done by including the file inputserrors.h and calling the function inputq_result_translate().
| typedef struct sw_inputq_setup sw_inputq_setup |
Name and contents of a RIP configuration.
The fields in the configuration structure may or may not be returned by a particular skin implementation. All fields except for the configuration name should be treated as optional, and suitable out-of-band values should be set to distinguish whether the RIP skin provided a value.
| typedef sw_inputq_result() sw_inputq_setup_fn(const sw_inputq_setup *setup, size_t size, void *data) |
Type of a callback function for iterating RIP configurations.
| [in] | setup | A structure containing the details of the configuration. |
| [in] | size | The size of the setup structure. This should be checked before dereferencing setup fields, different versions of the API may return extra configuration items. |
| data | The data pointer supplied to the inputq_iterate_setups() function. |
| typedef struct SWMSG_INPUTQ_CHANGE SWMSG_INPUTQ_CHANGE |
The message associated with SWEVT_INPUTQ_CHANGE events.
This message will be issued for all changes to the input queue.
| typedef struct SWMSG_INPUTS_ENABLE SWMSG_INPUTS_ENABLE |
The message associated with SWEVT_INPUTS_ENABLE events.
This message can be issued to request the current inputs status by setting enable to SW_INPUTS_ENABLE_UNKNOWN. It can also be issued to change the status by setting enable to SW_INPUTS_ENABLE_START or SW_INPUTS_ENABLE_STOP values. The RIP also issues updates to the state using this message if the inputs state is changed for any other reason. In particular an update with enable set to SW_INPUTS_ENABLE_STOPPED is issued when the process of stopping inputs completes.
Valid states for the SWMSG_INPUTS_ENABLE::enable field.
The inputs enable state determines whether the input system will continue to process incoming jobs. When enabled, the input system will take jobs from the active channels. After being requested to stop the RIP will complete any active job, but will not process any further jobs. The SWMSG_INPUTS_ENABLE::enable field is set to SW_INPUTS_ENABLE_STOP while the active job completes, and then to SW_INPUTS_ENABLE_STOPPED once it has completed.
Reasons for queue change event message.
| enum SW_INPUTQ_RESULT |
Return codes for API calls.
|
inlinestatic |
Translate an inputs-specific error code to a generic HqnResult error code.
| [in] | result | One of the SW_INPUTQ_RESULT values, or an error value greater than MON_CLASS_ERROR. |
The header file defining this function should be included explicitly in every C or C++ file that calls it.