|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
Raster manager output handler API version 20190618. More...
#include "rmoutputapi.h"
Data Fields | |
| struct RF_RASTER *(* | raster_create )(const char *name, const char *location, const char *datatype, const char *metadata) |
| Construct a raster object to pass to the raster_ready() method. More... | |
| HqBool(* | raster_ready )(int32 job_id, int32 page_id, int32 num_tiles, struct RF_RASTER **raster, sw_rmoutput_handled_fn *handled_fn, void *handled_data, HqBool page_complete, struct RF_ERROR **rferror) |
| Notify the Raster Manager that a raster is ready for output. More... | |
| char *(* | get_location )(const char *format,...) |
| Create a location ID suitable for use by raster_create(). More... | |
| void(* | free_object )(void *pointer) |
| Free any of the objects created by this API. More... | |
Raster manager output handler API version 20190618.
| void( * sw_rmoutput_api_20190618::free_object) (void *pointer) |
Free any of the objects created by this API.
| [in] | pointer | The object pointer returned by another method call. |
The objects allocated by other methods in this API MUST be freed when done using calls on this API, even if the backend is linked to the RIP Farm API directly. This applies to:
This function may safely be called with NULL pointer.
| char*( * sw_rmoutput_api_20190618::get_location) (const char *format,...) |
Create a location ID suitable for use by raster_create().
This call can be used to create and allocate a location identifier string, with elements representing the RIP Farm, the blade (machine), and process, combined with user-supplied strings and integer data.
This API call is an shim onto the RIP farm rf_location_id() API call.
| [in] | format | A format string used to determine what components to put in the location ID. |
NULL if there was an error creating the string. The string must be freed using rf_mem_free() after use.This function is conceptually similar to the printf() family of functions, but with a restricted set of valid format codes. It constructs an ID string according to a format, inserting components to represent different localities within the RIP farm.
As with printf(), literal characters are copied from the format string, and constructed components are inserted using format codes. Format codes are indicated in the format string using the % character. The set of valid format codes are:
char * pointer.int.int.int.char (which will be promoted to int).If any other format escape not on this list is used, this function will return NULL. In particular, note that field width and precision specifications are not supported.
Location components created by this function use characters from the union of valid characters in a domain name and an IP address (IPv4 and IPv6), i.e., a-z A-Z 0-9 - _ : .
Location IDs are passed to the Raster Manager for use in routing decisions and placement decisions. The Raster Manager will only ever compare location IDs for equality, it will never attempt to deconstruct them. However, OEM components can parse and deconstruct locations known to have been created by other OEM components.
Errors may be caused by a NULL or empty format string, an invalid argument to a format, an invalid format code, memory exhaustion, or an internal error in a function used to find an ID component.
| struct RF_RASTER*( * sw_rmoutput_api_20190618::raster_create) (const char *name, const char *location, const char *datatype, const char *metadata) |
Construct a raster object to pass to the raster_ready() method.
| [in] | name | A non-empty zero-terminated UTF-8 string indicating the name of this raster object. |
| [in] | location | A non-empty zero-terminated UTF-8 string indicating the location of this raster object. |
| [in] | datatype | A non-empty zero-terminated UTF-8 string indicating the data format of this raster object. |
| [in] | metadata | An optional zero-terminated UTF-8 string containing OEM-defined metadata associated with this raster object. |
NULL on error. This raster object MUST be passed to the raster_ready() method, or freed using the free_object() method if it is not passed to raster_ready().The name, location, and data format are non-empty zero-terminated strings. They are not interpreted by the raster manager, except that equality comparisons in all three imply the same raster, and that location comparisons can be used for decisions about proximity. The RIP's raster back-end and the final consumer of the rasters (the digital back-end) define the contents and contract of these strings. The metadata string is passed through from RIP's raster back-end to all consumers of the raster object, the RIP farm does not interpret or modify it in any way. GG recommend that this metadata is a stringified form of a structured data object (e.g. JSON).
The name, location and datatype of the raster object depends on OEM integration requirements. For example, disk based output might use the name of the file; a shared memory implementation might use a stringified memory handle. The location might be a machine name, a shared filesystem name, or any other string that can be compared to indicate the same locality of data. The location_id() method can be used to assist creation of RIP farm, machine, and process-specific locations if desired, however it is not necessary to use it to create the location parameter.
The datatype parameter will often be the same for all rasters from a particular raster backend. However, it may differ for a format where separation data is stored separately from a header that integrates the page information.
The optional metadata may be used by the raster backend to associate any information that the final consumer may find useful about this raster. For example, it may be useful to store the dimensions, separation name, and size of a disk-based raster object so that the consumer does not need to open a file and parse it.
If the OEM integration has no need for any of the name, location, or datatype, you must still provide non-empty strings that together uniquely identify this raster object.
All of the parameters to raster_create() are owned by the caller. They will be copied or reference-counted as appropriate by the API implementation.
| HqBool( * sw_rmoutput_api_20190618::raster_ready) (int32 job_id, int32 page_id, int32 num_tiles, struct RF_RASTER **raster, sw_rmoutput_handled_fn *handled_fn, void *handled_data, HqBool page_complete, struct RF_ERROR **rferror) |
Notify the Raster Manager that a raster is ready for output.
| [in] | job_id | The job ID that the raster belongs to. |
| [in] | page_id | The page ID that the raster belongs to. |
| [in] | num_tiles | The total number of tiles for this page when tiling. |
| [in] | raster | The location to find the raster description object created by raster_create(). This function takes ownership of the raster description object, whatever the return result. The raster description handed to this function must have been constructed using raster_create(). If there are no rasters for a page, then either this pointer may be NULL or it must point to NULL, and also the page_complete flag must be TRUE. |
| [in] | handled_fn | A function to call back when the raster has been handled by the final consumer. This function pointer may be NULL if there is no action to be taken by the raster backend when the raster is handled. If raster is NULL, this pointer must also be NULL. |
| [in] | handled_data | A data pointer to pass to the raster handled callback. |
| [in] | page_complete | This is the last raster that will be supplied for this page. This flag must be set if raster is NULL. |
| [out] | rferror | An optional pointer to a location to store error detail. If there is an error and detail is returned, the caller must free the error structure using the free_object() method. |
| TRUE | The raster was sent to the raster manager. The raster backend will receive a callback on the handled_fn (if non-NULL) when the final consumer has handled the raster, or an error occurs which causes cancellation of the job. rferror will be set to NULL. |
| FALSE | The raster ready message could not be sent to the raster manager. There will be no callback on handled_fn. rferror is set to an error, which must be freed using the free_object() method. If the error is NULL when FALSE is returned, then an API error has occurred which does not have detail available. |
The raster handler should make raster_ready() calls for each raster in a page. Rasters may have different formats, locations, and metadata if the raster backend and DBE desires. The final raster for a page should have the page_complete flag set to TRUE. It is possible to also call raster_ready() with raster NULL and page_complete TRUE after all of the rasters for a page have been generated, but is less efficient. A page need not have any rasters: a single call to raster_ready() for a page raster NULL and page_complete TRUE indicates a blank page.
NULL) may be called back at any time after this function returns, including during a call to an API functon, after the end of the job, and even after the raster backend is deselected. Only one handled_fn() callback will be made at a time, but the raster backend needs to ensure that the callback is thread-safe with respect to all other activity it performs.