|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
Binary large object callback API. More...
Files | |
| file | swblobapi.h |
| Header file defining the Binary large object callback API. | |
| file | swblobfactory.h |
| This header file provides definitions for the BLOB (Binary Large Object) factory used by the Binary large object callback API. | |
Data Structures | |
| struct | sw_blob_instance |
| An instance of the blob API implementation. More... | |
| struct | sw_blob_map |
| An instance of a blob memory mapping context. More... | |
| struct | sw_blob_api |
| A structure containing callback functions for BLOB (Binary Large Object) access. More... | |
| struct | sw_blob_factory_instance |
| An instance of the blob factory implementation. More... | |
| struct | sw_blob_factory_api |
| A structure containing callback functions to create BLOBs from named entities. More... | |
Typedefs | |
| typedef struct sw_blob_api | sw_blob_api |
| Type definition of the blob API implementation. | |
| typedef struct sw_blob_instance | sw_blob_instance |
| An instance of the blob API implementation. More... | |
| typedef struct sw_blob_map | sw_blob_map |
| An instance of a blob memory mapping context. More... | |
| typedef HqnResult | sw_blob_result |
| Type of return values from sw_blob_api functions. More... | |
| typedef int | sw_blob_protection |
| An integer used to indicate the type of encryption or protection applied to the original blob. | |
| typedef struct sw_blob_factory_api | sw_blob_factory_api |
| Type definition of the blob factory implementation. | |
| typedef struct sw_blob_factory_instance | sw_blob_factory_instance |
| An instance of the blob factory implementation. More... | |
Enumerations | |
| enum | { SW_BLOB_API_VERSION_20070614 = 1 , SW_BLOB_API_VERSION_20071115 } |
| Version numbers defined for the blob API. More... | |
| enum | SW_BLOB_RESULT { SW_BLOB_OK = HQN_RESULT_SUCCESS , SW_BLOB_ERROR = 1 , SW_BLOB_ERROR_EOF , SW_BLOB_ERROR_MEMORY , SW_BLOB_ERROR_INVALID , SW_BLOB_ERROR_ACCESS , SW_BLOB_ERROR_WRITE , SW_BLOB_ERROR_EXPIRED } |
| Return values from sw_blob_api functions. More... | |
| enum | { SW_BLOB_ALIGNMENT_NONE = 1 , SW_BLOB_ALIGNMENT_16BIT = 2 , SW_BLOB_ALIGNMENT_32BIT = 4 , SW_BLOB_ALIGNMENT_64BIT = 8 } |
| Possible values of the blob region map alignment. More... | |
| enum | { SW_BLOB_FACTORY_API_VERSION_20071116 = 1 } |
| Version numbers defined for the blob API. More... | |
Functions | |
| HqnResult | swblob_result_translate (sw_blob_result result) |
| Translate a blob API-specific error code to a generic HqnResult error code. More... | |
Binary large object callback API.
The BLOB (Binary Large Object) API is provided to modules which may need to do read or write large data objects provided by the RIP. Some APIs and callback functions are provided with a sw_blob_instance pointer. This is a pointer to an instantiation of a BLOB callback API. The callback function or API functions that have access to the sw_blob_instance pointer may call methods on the instance's sw_blob_instance::implementation pointer (of type sw_blob_api) to read and write large binary objects provided by the API.
The BLOB interface is used to access large data chunks using a memory mapping API or a file reading API. A BLOB instance passed to a callback or API is only valid for the lifetime of the callback. If you need to retain access to the BLOB, you must call sw_blob_api::open() to retain a reference to the BLOB. This reference must be released by calling sw_blob_api::close() when access to the BLOB is no longer needed.
The size of a BLOB can be determined by calling sw_blob_api::length().
The BLOB may be treated as a file by calling sw_blob_api::read() to copy data from the BLOB to a local buffer, or calling sw_blob_api::write() to copy data from a local buffer into the BLOB. The current read/write position in a BLOB can be determined by calling sw_blob_api::tell() and reset by calling sw_blob_api::seek(). The methods that treat a BLOB as a file should not be mixed with methods that memory map the BLOB.
Memory mapping opens "windows" into the BLOB data, which can be accessed directly by the client. The BLOB data can be mapped into memory buffers managed by the API by calling sw_blob_api::map_open() to create a mapping context, sw_blob_api::map_region() one or more times to map region(s) into memory in that context, and then sw_blob_api::map_close() to close and invalidate the mappings in that context. More than one memory mapping context may be open at any time. The alignment of data in memory mappings may be specified, but if the alignment requested differs from the underlying alignment of the BLOB data, there may be memory copy operations performed by the API.
BLOB data may be protected. The type of protection may be determined by calling sw_blob_api::protection(). This is most useful as an input into a decryption filter, e.g., as a /Strategy for encrypted fonts.
A utility function, swblob_result_translate(), is provided to translate BLOB API-specific result values to generic HqnResult result codes that can be passed to the RIP or as return values for other APIs.
The BLOB factory is used by modules that need to initiate access to blobs independently of the core RIP. Similarly to the BLOB API, a sw_blob_factory_instance will be provided to any callback or API that may need the BLOB factory API. The client can call the sw_blob_factory_instance::implementation pointer's sw_blob_factory_api methods to create a sw_blob_instance, which can then be manipulated using the normal sw_blob_instance::implementation pointer methods.
The BLOB factory API has only one method, sw_blob_factory_api::open_named(). This method creates a sw_blob_instance pointer from a named file or object, returning a BLOB instance that can be manipulated through its sw_blob_instance::implementation pointer's methods. This BLOB should be closed by calling sw_blob_api::close() when it is no longer needed.
| typedef struct sw_blob_factory_instance sw_blob_factory_instance |
An instance of the blob factory implementation.
This structure represents a parameterised blob factory.
There is only one public field in this structure, which is the required implementation pointer. The RIP will subclass instances to add private instance specific data.
The RIP manages the memory for this structure. Modules should not attempt to copy the structure, or access any data except the public fields.
| typedef struct sw_blob_instance sw_blob_instance |
An instance of the blob API implementation.
This structure represents an open data source.
There is only one public field in this structure, which is the required implementation pointer. The RIP will subclass instances to add private instance specific data.
The RIP manages the memory for this structure. Modules should not attempt to copy the structure, or access any data except the public fields.
| typedef struct sw_blob_map sw_blob_map |
An instance of a blob memory mapping context.
There is only one public field in this structure, which is the required implementation pointer. The RIP will subclass instances to add private instance specific data.
The RIP manages the memory for this structure. Modules should not attempt to copy the structure, or access any data except the public fields.
| typedef HqnResult sw_blob_result |
Type of return values from sw_blob_api functions.
This is a subclass of HqnResult that also supports some specific extra error codes generated by sw_blob_api functions (declared as the SW_BLOB_RESULT enumeration). Before assigning to values of HqnResult type or any of its other subclasses, sw_blob_result values must be converted to change the data API specific values to HQN_RESULT_SUCCESS or a monitor UID error code greater than MON_CLASS_ERROR. This can be done by calling the function swblob_result_translate().
| anonymous enum |
| anonymous enum |
Possible values of the blob region map alignment.
| anonymous enum |
| enum SW_BLOB_RESULT |
Return values from sw_blob_api functions.
| Enumerator | |
|---|---|
| SW_BLOB_OK | Success return value for sw_blob_api methods. |
| SW_BLOB_ERROR | Non-specific error, also minimum error value. Please avoid using this if possible. |
| SW_BLOB_ERROR_EOF | End of data stream. |
| SW_BLOB_ERROR_MEMORY | Out of memory. |
| SW_BLOB_ERROR_INVALID | An invalid blob reference was used. |
| SW_BLOB_ERROR_ACCESS | The access mode requested cannot be used. |
| SW_BLOB_ERROR_WRITE | A write to the blob failed. |
| SW_BLOB_ERROR_EXPIRED | The underlying data source has expired. |
| HqnResult swblob_result_translate | ( | sw_blob_result | result | ) |
Translate a blob API-specific error code to a generic HqnResult error code.
| [in] | result | One of the SW_BLOB_RESULT values, or an error value greater than MON_CLASS_ERROR. |