|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
A structure containing callback functions for structured data access. More...
#include "swdataapi.h"
Data Fields | |
| sw_api_info | info |
| sw_data_result(* | get_indexed )(const sw_datum *array, size_t index, sw_datum *value) |
| Get an indexed value from an array or stack datum. More... | |
| sw_data_result(* | set_indexed )(sw_datum *array, size_t index, const sw_datum *value) |
| Store an indexed value in an array or stack datum. More... | |
| sw_data_result(* | get_keyed )(const sw_datum *dict, const sw_datum *key, sw_datum *value) |
| Get a keyed value from a dictionary datum. More... | |
| sw_data_result(* | set_keyed )(sw_datum *dict, const sw_datum *key, const sw_datum *value) |
| Store a keyed value in a dictionary datum. More... | |
| sw_data_result(* | match )(const sw_datum *composite, sw_data_match *match, size_t match_length) |
| Match multiple data entries in a dictionary or array datum. More... | |
| sw_data_result(* | iterate_begin )(const sw_datum *composite, sw_data_iterator **iterator) |
| Start a new iteration over a dictionary or array datum. More... | |
| sw_data_result(* | iterate_next )(const sw_datum *composite, sw_data_iterator *iterator, sw_datum *key, sw_datum *value) |
| Get a key-value pair from a dictionary or array datum iteration. More... | |
| void(* | iterate_end )(const sw_datum *composite, sw_data_iterator **iterator) |
| Discard resources associated with a data structure iterator state. More... | |
| HqBool(* | equal )(const sw_datum *one, const sw_datum *two) |
| Compare two datums for equality. More... | |
| sw_data_result(* | open_blob )(const sw_datum *datum, int32 mode, sw_blob_instance **blob) |
| Open a SW_DATUM_TYPE_BLOB datum for access via the sw_blob_api interface. More... | |
| sw_data_result(* | pop )(sw_datum *stack) |
| Pop the top element from the stack. A stack is an array datum of subtype SW_DATUM_SUBTYPE_STACK_ARRAY. More... | |
| sw_data_result(* | push )(sw_datum *stack, const sw_datum *value) |
| Push an entry onto a stack. A stack is an array datum of subtype SW_DATUM_SUBTYPE_STACK_ARRAY. More... | |
| sw_data_result(* | retain )(const sw_datum *datum, sw_datum **retained) |
| Retain a datum until released. More... | |
| sw_data_result(* | release )(sw_datum **retained) |
| Release a composite datum that was previously retained. More... | |
A structure containing callback functions for structured data access.
Data references provided from the RIP are automatically invalidated at the end of the callback that passed them to a module. All data that is to be stored between calls to the module must be copied from the RIP.
Note that in the case of complex types such as strings, arrays and dictionaries, it is not enough to copy the sw_datum - its contents must be copied. This includes the bytes of a strings, and all the elements of an array or dictionary. It is not usually necessary to copy datums in this way.
Creators of sw_datum complex types can implement this API, pointing the datum's owner field at their sw_data_api structure, to enable on-demand creation or delivery of array, stack and dictionary contents. In such a case, the implementor uses the datum's value.opaque field for its own purposes. A sw_data_api created for this purpose need only implement those methods that are relevant - NULL methods return SW_DATA_ERROR_INVALIDACCESS if used.
Compare two datums for equality.
| FALSE | the values were of incomparable types, or were not equal. |
| TRUE | the values were of comparable types of the same value. |
This is a strict equality test for composites, but is otherwise an equivalence test, so the numeric value of a float can be equal to the value of an integer, for example. For composites such as arrays this does not compare the contents, but tests whether they are the same array.
| sw_data_result( * sw_data_api::get_indexed) ( const sw_datum *array, size_t index, sw_datum *value) |
Get an indexed value from an array or stack datum.
| [in] | array | An array or stack datum from which an indexed value will be extracted. |
| [in] | index | The index of the value to extract. Zero means the first element of the array, or the topmost element of the stack. |
| [out] | value | The location to be filled in with the returned value. |
| SW_DATA_OK | Success. The value entry is filled with the indexed array or stack entry. |
| SW_DATA_ERROR_RANGECHECK | Returned if the index is out of range. |
| SW_DATA_ERROR_TYPECHECK | Returned if the indexed value is an unsupported type or the first parameter isn't an array. |
| SW_DATA_ERROR_INVALIDACCESS | Returned if the array was not readable. |
| sw_data_result( * sw_data_api::get_keyed) ( const sw_datum *dict, const sw_datum *key, sw_datum *value) |
Get a keyed value from a dictionary datum.
| [in] | dict | A dictionary datum from which a keyed value will be extracted. |
| [in] | key | A key for the value to extract. The type of the key may be restricted to transparent type (strings, integer, boolean, real, null), depending on the owner of the dictionary. |
| [out] | value | The location to be filled in with the returned value. |
| SW_DATA_OK | Success. The value entry is filled with the keyed array entry. |
| SW_DATA_ERROR_UNDEFINED | Returned if the key does not exist in the dictionary. |
| SW_DATA_ERROR_TYPECHECK | Returned if the keyed value is an unsupported type or the first parameter is not a dictionary. |
| SW_DATA_ERROR_INVALIDACCESS | Returned if the dictionary was not readable. |
| sw_api_info sw_data_api::info |
Version number, name, display name, size. This is REQUIRED to be the first field.
| sw_data_result( * sw_data_api::iterate_begin) ( const sw_datum *composite, sw_data_iterator **iterator) |
Start a new iteration over a dictionary or array datum.
| [in] | composite | The datum to iterate over. |
| [out] | iterator | A pointer to an opaque iteration state. |
| SW_DATA_OK | Returned if the iterator was started. sw_data_api::iterate_end() must be called when complete to dispose of the iterator state. |
| SW_DATA_ERROR_TYPECHECK | Returned if the composite datum is not of a suitable type to iterate. |
| SW_DATA_ERROR_MEMORY | Returned if the iteration state could not be created because of a memory allocation failure. |
| SW_DATA_ERROR_INVALIDACCESS | Returned if the composite datum was not readable. |
| void( * sw_data_api::iterate_end) ( const sw_datum *composite, sw_data_iterator **iterator) |
Discard resources associated with a data structure iterator state.
If sw_data_api::iterate_begin() succeeded, this function must be called to dispose of the iterator state.
| [in] | composite | The data structure being iterated. |
| [in,out] | iterator | The location where the iterator state is stored. The iterator state pointer will be invalidated on exit. |
| sw_data_result( * sw_data_api::iterate_next) ( const sw_datum *composite, sw_data_iterator *iterator, sw_datum *key, sw_datum *value) |
Get a key-value pair from a dictionary or array datum iteration.
| [in] | composite | The datum being iterated. |
| [in] | iterator | An iterator state previously created by iterate_begin(). |
| [out] | key | A unique key identifying the datum in the composite structure. When iterating over arrays, this will be set to an integer datum with the index of the associated value. |
| [out] | value | The value associated with key in the composite structure. |
| SW_DATA_OK | Success. The key and value parameters are filled in. |
| SW_DATA_FINISHED | Returned when there are no more keys to iterate over. |
| SW_DATA_ERROR_MEMORY | Returned if the iteration state could not be updated because of a memory allocation failure. |
| sw_data_result( * sw_data_api::match) ( const sw_datum *composite, sw_data_match *match, size_t match_length) |
Match multiple data entries in a dictionary or array datum.
| [in] | composite | An array or dictionary datum from which values will be extracted. |
| [in,out] | match | An array of match structures, determining the key to match, what types are acceptable for the match, how to treat type mismatches or missing values, and where to store the value. |
| [in] | match_length | The number of entries to match. |
| SW_DATA_OK | Success. The match result data are updated with the value of the extracted entries, or set to SW_DATUM_TYPE_NOTHING if the key was not matched but was optional. |
| SW_DATA_ERROR_UNDEFINED | Returned if a required entry was not present. The match data should not be examined if this error occurs. |
| SW_DATA_ERROR_TYPECHECK | Returned if a matched value has the wrong type, and the SW_DATUM_TYPE_INVALID bit was not set in the allowed type mask of the match. The match data should not be examined if this error occurs. This error is also returned if the first parameter is not an array or dictionary. |
| SW_DATA_ERROR_INVALIDACCESS | Returned if the data structure to match was not readable. The match data should not be examined if this error occurs. |
| sw_data_result( * sw_data_api::open_blob) ( const sw_datum *datum, int32 mode, sw_blob_instance **blob) |
Open a SW_DATUM_TYPE_BLOB datum for access via the sw_blob_api interface.
| [in] | datum | A datum of type SW_DATUM_TYPE_BLOB. |
| [in] | mode | An access mode of SW_RDONLY, SW_WRONLY, or SW_RDWR, possibly combined with the flags SW_FONT and SW_EXCL, as defined in swdevice.h. If none of the access mode flags are set, the RIP will derive the access mode from the datum itself. |
| [in] | blob | A pointer to a handle for a sw_blob_instance. |
| sw_data_result( * sw_data_api::pop) ( sw_datum *stack) |
Pop the top element from the stack. A stack is an array datum of subtype SW_DATUM_SUBTYPE_STACK_ARRAY.
| [in] | stack | A stack datum from which the datum will be removed. |
| SW_DATA_OK | Success. The top entry was popped from the stack. |
| SW_DATA_ERROR_RANGECHECK | Returned if the stack is empty. |
| SW_DATA_ERROR_TYPECHECK | Returned if stack is not an array datum of subtype SW_DATUM_SUBTYPE_STACK_ARRAY. |
| SW_DATA_ERROR_INVALIDACCESS | Returned if the stack was not readable or mutable. |
Note that like set_indexed, pop implicitly invalidates any opaque datum representing the value that has been popped from the stack. e.g.:
Do not change or pop an opaque datum until you have finished with it. See set_indexed for more details.
| sw_data_result( * sw_data_api::push) ( sw_datum *stack, const sw_datum *value) |
Push an entry onto a stack. A stack is an array datum of subtype SW_DATUM_SUBTYPE_STACK_ARRAY.
| [in] | stack | A stack datum onto which the datum will be added. |
| [in] | value | The datum to be pushed onto the top of the stack. |
| SW_DATA_OK | Success. The value entry has been pushed onto the top of the stack. |
| SW_DATA_ERROR_RANGECHECK | Returned if the stack is full. |
| SW_DATA_ERROR_TYPECHECK | Returned if stack is not an array datum of subtype SW_DATUM_SUBTYPE_STACK_ARRAY or the value is not of a suitable type. |
| SW_DATA_ERROR_MEMORY | Returned if a memory allocation failed while trying to push the value. |
| SW_DATA_ERROR_INVALIDACCESS | Returned if the stack was not writeable. |
| sw_data_result( * sw_data_api::release) ( sw_datum **retained) |
Release a composite datum that was previously retained.
| [in,out] | retained | The location of a retained datum pointer that was previously retained using sw_data_api::retain(). If the datum pointer was valid, this is set to NULL on exit. |
| SW_DATA_OK | if the datum was released. Datum objects that were retained successfully will always be able to be released. |
| SW_DATA_ERROR_SYNTAX | if the location of the datum or the datum is invalid. |
| SW_DATA_ERROR_INVALIDACCESS | if the datum could not be released for any other reason. |
| sw_data_result( * sw_data_api::retain) ( const sw_datum *datum, sw_datum **retained) |
Retain a datum until released.
| [in] | datum | A pointer to the datum to retain. |
| [out] | retained | A pointer to a location in which a new datum pointer will be stored. Access to the retained datum should always be through this pointer. |
Not all datum objects may be retained (generally simple datum objects, and composite objects that do not contain unsupported datum types). Datum that are successfully retained must be released before the RIP shuts down.
In some cases, the retained datum pointer may be the same as the original datum pointer, but this is not guaranteed. The sw_data_api::release() call must always be called using the new retained datum pointer. The datum object will become invalid and should not be dereferenced after the matching release call.
Data returned by the sw_data_api::get_indexed(), sw_data_api::get_keyed(), and iteration methods are temporary copies of the retained data. If the retained data are released, the temporary copies may cease to be valid. Retaining the temporary copy may create a new retained copy of the data, distinct from the original, or may share the original retained data. The exact behaviour of retaining the temporary copies is not guaranteed.
| SW_DATA_OK | if the datum could be retained. The datum pointer will remain valid until after a matching sw_data_api::release() call. |
| SW_DATA_ERROR_SYNTAX | if the datum is invalid. |
| SW_DATA_ERROR_MEMORY | if the datum could not be retained because of memory exhaustion. |
| SW_DATA_ERROR_RANGECHECK | if the datum is retained too many times. |
| SW_DATA_ERROR_INVALIDACCESS | if the datum could not be retained for any other reason. |
| sw_data_result( * sw_data_api::set_indexed) ( sw_datum *array, size_t index, const sw_datum *value) |
Store an indexed value in an array or stack datum.
| [in] | array | An array or stack datum into which an indexed value will be stored. |
| [in] | index | The index at which to store the value. Zero means the first element of the array, or the topmost element of the stack. |
| [in] | value | The datum to store into the array. Values in local module memory will be deep-copied when storing into RIP owned arrays or stacks. |
| SW_DATA_OK | Returned if successful. |
| SW_DATA_ERROR_TYPECHECK | Returned if the first parameter isn't an array. |
| SW_DATA_ERROR_RANGECHECK | Returned if the index is out of range. |
| SW_DATA_ERROR_INVALIDACCESS | Returned if the value cannot be stored into the array or stack. |
| SW_DATA_ERROR_MEMORY | Returned if a memory allocation failed while trying to store the value. |
Note that using set_indexed to change an element of an array or stack will invalidate any opaque datum already fetched from that index - datums represent data, they are not necessarily an independent copy of that data. e.g.:
In the above example, array index 0 is changed after having been fetched, so the fetched opaque datum no longer represents the actual data. Any attempt to use that outdated representation can fail in unpredictable and serious ways.
| sw_data_result( * sw_data_api::set_keyed) ( sw_datum *dict, const sw_datum *key, const sw_datum *value) |
Store a keyed value in a dictionary datum.
| [in] | dict | A dictionary datum into which a keyed value will be stored. |
| [in] | key | A key for the value to store. The type of the key may be restricted to transparent type (strings, integer, boolean, real, null), depending on the owner of the dictionary. |
| [in] | value | The datum to store into the dictionary. Values in local module memory will be deep-copied when stored in RIP owned dictionaries. |
| SW_DATA_OK | Returned if successful. |
| SW_DATA_ERROR_TYPECHECK | Returned if the first parameter is not a dictionary or the value is not of an appropriate type. |
| SW_DATA_ERROR_INVALIDACCESS | Returned if the value cannot be stored into the dictionary. |
| SW_DATA_ERROR_MEMORY | Returned if a memory allocation failed while trying to store the value. |
Note that like set_indexed, changing a dictionary value with set_keyed will invalidate any opaque datum fetched for that key. See set_indexed for details.