|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
A structure containing callback functions for BLOB (Binary Large Object) access. More...
#include "swblobapi.h"
Data Fields | |
| sw_api_info | info |
| Version number, name, display name, instance size. More... | |
| sw_blob_result(* | open )(sw_blob_instance *blob, int mode, sw_blob_instance **reference) |
| Create a retainable reference to a blob data source. More... | |
| void(* | close )(sw_blob_instance **blob) |
| Close a blob reference, releasing its resources. More... | |
| sw_blob_result(* | length )(sw_blob_instance *blob, Hq32x2 *bytes) |
| Get the length of a blob. More... | |
| sw_blob_result(* | read )(sw_blob_instance *blob, void *buffer, size_t byteswanted, size_t *bytesread) |
| Read a buffer of data from the current position in a blob. More... | |
| sw_blob_result(* | write )(sw_blob_instance *blob, void *buffer, size_t bytestowrite) |
| Write a buffer of data at the current position in a blob. More... | |
| sw_blob_result(* | seek )(sw_blob_instance *blob, Hq32x2 where, int offset) |
| Adjust the blob's current position. More... | |
| sw_blob_result(* | tell )(sw_blob_instance *blob, Hq32x2 *where) |
| Query the current position in the blob. More... | |
| sw_blob_result(* | protection )(sw_blob_instance *blob, sw_blob_protection *protection) |
| Query the type of protection used for the blob data. More... | |
| sw_blob_result(* | map_open )(sw_blob_instance *blob, sw_blob_map **map) |
| Open a memory mapping context for a blob. More... | |
| sw_blob_result(* | map_region )(sw_blob_map *map, Hq32x2 start, size_t length, size_t alignment, uint8 **mapping) |
| Map a section of a blob into a contiguous block of memory. More... | |
| void(* | map_close )(sw_blob_map **map) |
| Close a memory mapping context for a blob. More... | |
A structure containing callback functions for BLOB (Binary Large Object) access.
The rip provides the module with an API that can be used to access data sources through either a memory mapping interface or a file-like API. Where possible, the module should use the memory mapping interface to directly read data, because the RIP may be able to use zero-copy techniques to provide data.
| void( * sw_blob_api::close) ( sw_blob_instance **blob) |
Close a blob reference, releasing its resources.
Note that it is permissible to close a blob before its memory mapping contexts are closed, however any resources used by the blob will not actually be released until the last mapping context is closed.
| [in,out] | blob | A pointer to the blob reference to be closed. The blob reference is invalidated by this call. |
| sw_api_info sw_blob_api::info |
Version number, name, display name, instance size.
This is REQUIRED to be the first field.
| sw_blob_result( * sw_blob_api::length) ( sw_blob_instance *blob, Hq32x2 *bytes) |
Get the length of a blob.
| [in] | blob | The blob whose length is to be found. |
| [out] | bytes | On exit, the length of the blob. The total length of a blob may not be available if the underlying data source is streamed. |
| SW_BLOB_OK | Returned if the length was available, in which case the bytes parameter contains the length of the data source. |
| SW_BLOB_ERROR_ACCESS | Returned if the length of the blob was not available, in which case the bytes parameter is not modified. |
| SW_BLOB_ERROR_INVALID | Returned if the blob instance is invalid. |
| SW_BLOB_ERROR_EXPIRED | Returned if the underlying data source has expired. |
| void( * sw_blob_api::map_close) ( sw_blob_map **map) |
Close a memory mapping context for a blob.
If map_open() succeeded, this method MUST be called to delete the memory mapping context. Calling this method allows the RIP to reclaim allocated buffers in the memory mapping context.
Note that it is permissible to close a blob before its memory mapping contexts are closed, however any resources required by the blob will not actually be released until the last mapping context is closed.
| [in,out] | map | The memory mapping context to be closed. The mapping context is invalidated by this call. |
After this call, any pointers returned by the map_region() method in this context must not be dereferenced.
| sw_blob_result( * sw_blob_api::map_open) ( sw_blob_instance *blob, sw_blob_map **map) |
Open a memory mapping context for a blob.
The blob memory mapping interface allows clients to request access to regions of data which can be accessed directly through memory pointers. If possible, the RIP will provide these pointers without copying data.
| [in] | blob | The blob which to which the subsequent memory mapping operations apply. |
| [out] | map | On a successful exit, an open memory mapping context will be stored here. |
Multiple memory map contexts may be opened on the same blob simultaneously. All mappings created in a context will remain valid until the corresponding map_close() call, after which they will cease to be be valid and pointers to the mapped memory must not be dereferenced. The RIP will allocate and deallocate memory as necessary to map requested sections of a blob. Modules must not modify RIP memory returned by the memory mapping API.
| SW_BLOB_OK | Returned if the mapping context was created successfully. |
| SW_BLOB_ERROR_MEMORY | Returned if the RIP cannot allocate a blob mapping context. |
| SW_BLOB_ERROR_ACCESS | Returned if the underlying data source cannot be read. |
| SW_BLOB_ERROR_INVALID | Returned if the blob instance is invalid. |
| SW_BLOB_ERROR_EXPIRED | Returned if the underlying data source is out of scope. |
If the map_open() call succeeds, a corresponding map_close() call MUST be made when the access to the mapped sections is complete, to allow the RIP to recover the resources associated with the mapping context.
It is permissable to close a blob reference which has open memory mapping contexts, and continue to use the memory mapping contexts. In this case, resources used by the blob will not be released until the last memory mapping context is closed.
| sw_blob_result( * sw_blob_api::map_region) ( sw_blob_map *map, Hq32x2 start, size_t length, size_t alignment, uint8 **mapping) |
Map a section of a blob into a contiguous block of memory.
This call ensures that a section of the blob starting at the specified start address and with the specified length is mapped into memory, and returns a pointer to the memory in which the blob is mapped. The data mapping will not copy data if possible, but if different alignments are requested, natural boundaries in the underlying data source are crossed, or overlapping regions are mapped, the data may be copied into temporary buffers managed by the RIP. All mapping pointers are invalid as soon as the memory mapping context is closed, and must not be dereferenced.
Memory mapping a region does not modify the current blob position.
| [in] | map | The memory mapping context in which the mapping is to be made. |
| [in] | start | The start location of the data to be mapped in the blob. |
| [in] | length | The length of the data region to be mapped. |
| [in] | alignment | This parameter determines how the returned data pointer should be aligned. A value of SW_BLOB_ALIGNMENT_NONE indicates that any alignment is acceptable. The value SW_BLOB_ALIGNMENT_16BIT is used for 16-bit alignment, SW_BLOB_ALIGNMENT_32BIT for 32-bit alignment, and SW_BLOB_ALIGNMENT_64BIT for 64-bit alignment. For types of these sizes, the alignment enumeration values are the same as sizeof(type). |
| [out] | mapping | After a successful exit, a pointer to a contiguous block of memory containing the data requested, aligned as requested, is stored in this location. The pointer remains valid until the mapping context is closed. |
| SW_BLOB_OK | Returned if the mapping is made successfully. |
| SW_BLOB_ERROR_MEMORY | Returned if the RIP cannot allocate a mapping buffer. |
| SW_BLOB_ERROR_EOF | Returned if the mapping extends beyond the end of the underlying data source. |
| SW_BLOB_ERROR_INVALID | Returned if the mapping context, mapping location pointer, or the alignment parameter are invalid. |
| SW_BLOB_ERROR_EXPIRED | Returned if the underlying data source is out of scope. |
| sw_blob_result( * sw_blob_api::open) ( sw_blob_instance *blob, int mode, sw_blob_instance **reference) |
Create a retainable reference to a blob data source.
This method should be used whenever a module wishes to retain a reference to a blob after the end of the call that supplied it. Data sources supplied by the RIP are automatically invalidated at the end of the method that passed them to a module.
If the data source backing the blob becomes invalid before the blob is closed, then all of the API calls referring to the blob or to memory maps opened from it will return error codes (SW_BLOB_ERROR_EXPIRED usually).
A module should release all references to a blob as soon as possible to ensure best performance.
This method can also be used to request a different set of access permissions for a blob.
| [in] | blob | An existing blob data source. |
| [in] | mode | An access mode composed of one of SW_RDWR, SW_WRONLY, or SW_RDONLY, possibly combined with the flags SW_EXCL and SW_FONT defined in swdevice.h. |
| [out] | reference | A pointer in which the new blob reference will be stored. |
| SW_BLOB_OK | Returned if the blob was opened, in which case the reference parameter is updated with a reference to the blob. The close() call must be called when the module no longer needs the blob to allow the RIP to deallocate the resources used by the blob. |
| SW_BLOB_ERROR_MEMORY | Returned if the RIP cannot allocate a blob reference. |
| SW_BLOB_ERROR_ACCESS | Returned if the access mode does not match the capability of the underlying data source. Some blob implementations may check access lazily, and may allow creation of blob references which cannot be accessed for read and/or write. Such an implementation may return SW_BLOB_OK to this method call, but fail with SW_BLOB_ERROR_ACCESS later. |
| SW_BLOB_ERROR_INVALID | Returned if the blob parameter is invalid. |
| SW_BLOB_ERROR_EXPIRED | Returned if the blob parameter has passed out of scope. |
| sw_blob_result( * sw_blob_api::protection) ( sw_blob_instance *blob, sw_blob_protection *protection) |
Query the type of protection used for the blob data.
The protection type is an integer, representing the type of encryption or protection of the original blob source. The value of 0 indicates no protection. Values in the range 1-255 are reserved for use by Global Graphics.
| [in] | blob | The blob whose protection type is to be found. |
| [out] | protection | One of the sw_blob_protection enumeration values. |
| SW_BLOB_OK | Returned if the blob was valid, in which case the type of protection is stored in the protection parameter. |
| SW_BLOB_ERROR_INVALID | Returned if the blob instance is invalid. |
| SW_BLOB_ERROR_EXPIRED | Returned if the underlying data source is out of scope. |
| sw_blob_result( * sw_blob_api::read) ( sw_blob_instance *blob, void *buffer, size_t byteswanted, size_t *bytesread) |
Read a buffer of data from the current position in a blob.
This call fills a buffer with bytes read from the current position of the blob, updating the current position to point after the bytes read. It will return less than the requested number of bytes only if the end of the data source was encountered, or an error occurred.
| [in] | blob | The blob from which to read data. |
| [out] | buffer | A buffer into which the data will be read. |
| [in] | byteswanted | The number of bytes to read. The caller is responsible for making sure the buffer is at least this size. |
| [out] | bytesread | On a successful exit, the number of bytes actually read from the blob is stored here. |
| SW_BLOB_OK | Returned if bytes were read from the blob without an error occurring. The bytesread parameter will be updated with the amount of data actually stored in the buffer. The read() function will try to fully satisfy the read request; the only time fewer than the requested number of bytes will be returned is when the request spans the end of the data stream. |
| SW_BLOB_ERROR_EOF | If there is no data left to read, this will be returned, and a value of zero will be stored in the bytesread field. |
| SW_BLOB_ERROR_INVALID | Returned if the blob instance is invalid. |
| SW_BLOB_ERROR_EXPIRED | Returned if the underlying data source is no longer valid. |
| SW_BLOB_ERROR_ACCESS | Returned if the blob does not support read access. |
| sw_blob_result( * sw_blob_api::seek) ( sw_blob_instance *blob, Hq32x2 where, int offset) |
Adjust the blob's current position.
Some blob implementations may lazily update the position in the underlying data source, and so may return success for this method, but fail on a subsequent read or a write.
| [in] | blob | The blob whose current position is to be set. |
| [in] | where | The new current position of the blob, relative to the offset. |
| [in] | offset | One of the constants SW_SET, SW_INCR, or SW_XTND, defined in swdevice.h. The offset indicates whether the position set is relative to the start, current position, or end of the underlying data source respectively. |
| SW_BLOB_OK | Returned if the position was successfully updated. |
| SW_BLOB_ERROR_INVALID | Returned if the blob instance is invalid. |
| SW_BLOB_ERROR_EXPIRED | Returned if the underlying data source is out of scope. |
| SW_BLOB_ERROR_EOF | Returned if the position is set beyond the end of the data source, and the blob is not writable (if it is, the data source will be extended as necessary). |
| SW_BLOB_ERROR_ACCESS | Returned if the underlying data source is not seekable. |
| sw_blob_result( * sw_blob_api::tell) ( sw_blob_instance *blob, Hq32x2 *where) |
Query the current position in the blob.
| [in] | blob | The blob whose current position is to be found. |
| [out] | where | On a successful exit, the current position in the blob is stored here. |
| SW_BLOB_OK | Returned if the blob was valid, in which case the location is stored in the where parameter. |
| SW_BLOB_ERROR_INVALID | Returned if the blob instance is invalid. |
| SW_BLOB_ERROR_EXPIRED | Returned if the underlying data source is out of scope. |
| sw_blob_result( * sw_blob_api::write) ( sw_blob_instance *blob, void *buffer, size_t bytestowrite) |
Write a buffer of data at the current position in a blob.
This call stores a buffer of bytes at the current position in the blob, updating the current position to point after the bytes written. It will only write less than the requested number of bytes if an error occurred.
Note that blobs cannot be written to if any memory mapping contexts of any blob instances are mapped onto the underlying data source.
| [in] | blob | The blob to which data is written. |
| [in] | buffer | A buffer from which the data will be written. |
| [in] | bytestowrite | The number of bytes to write. The caller is responsible for making sure the buffer is at least this size. |
| SW_BLOB_OK | Returned if the write request was fully completed. |
| SW_BLOB_ERROR_INVALID | Returned if the blob instance is invalid. |
| SW_BLOB_ERROR_EXPIRED | Returned if the underlying data source is no longer valid. |
| SW_BLOB_ERROR_ACCESS | Returned if the blob does not support write access, or if any memory mapping contexts are currently open on the blob. |