Name
DeserializeItem -- deserialize next item (V9.0)
Synopsis
int ok = DeserializeItem(APTR handle, struct hwSerializeItemInfo *key,
     struct hwSerializeItemInfo *val, int *done, struct hwTagList *tags);
Function
This function must deserialize the next item from the data provided by the readfunc that Hollywood passed to your InitSerializer() function and store its key and value in the key and val parameters. When all items have been deserialized, done must be set to True. handle will be a serializer created by InitSerializer().

Both, the key and the value of the deserialized item must be returned in a struct hwSerializeItemInfo structure. This structure looks like this:

 
struct hwSerializeItemInfo
{
    int Type;
    APTR Data;
    int Length;
    ULONG Flags;
};

Here is an explanation of the individual structure members:

Type:
This must be set to the type of the deserialized key and value. This must be one of the following types:

HWSERIALIZETYPE_DOUBLE:
Key or value is a double number. Data must be set to a pointer to a double containing that number. Length must be set to sizeof(double), i.e. 8.

HWSERIALIZETYPE_STRING:
Key or value is a string. Data must be set to a pointer to this string. The string need not be NULL-terminated because Length must be set to the string length in bytes. Note that strings used as values may also contain binary data. Keys must always be text, though. If Length is 0 Data should be NULL as well.

HWSERIALIZETYPE_TABLE:
Value is a table. Note that this can only be used for values. Tables cannot be used as keys. Data must be set NULL. For each table you deserialize, you must deserialize a head and a tail item. The head item must have Length set to 1. It signals to Hollywood that a new table is about to be deserialized. After returning the head item, DeserializeItem() must then return all items in that table. After it has done so, you must deserialize a tail item for the table by setting Length to 0. This signals to Hollywood that all table items have been deserialized. Thus, the Length field can be interpreted as opening (1) or closing (0) the table that is to be deserialized.

HWSERIALIZETYPE_FUNCTION:
Value is a function. Note that this can only be used for values. Functions cannot be used as keys. Data must be set to a memory buffer containing the byte code of the function. Length must be set to the length of the byte code in bytes.

Data:
Depends on the Type member. See above.

Length:
Depends on the Type member. See above.

Flags:
Currently unused. Must be set to 0.

Note that to get the data to be deserialized, DeserializeItem() has to call the readfunc() that was passed to your plugin when Hollywood called your InitSerializer() function. See InitSerializer for details. This function looks like this:

 
int readfunc(APTR buf, int len, APTR userdata);

The following arguments must be passed:

buf:
Buffer to copy data to.

len:
Number of bytes to read.

userdata:
The user data that was passed to your InitSerializer() function.

The return value of readfunc() will be the number of bytes successfully read. Note that this can be less than the number of bytes requested. Once readfunc() returns 0, there is no more data to deserialize.

Inputs
handle
serializer handle allocated by InitSerializer()
key
store the key of the deserialized item here
val
store the value of the deserialized item here
done
once all items have been deserialized, write True to this parameter
tags
reserved for future use, currently always NULL
Results
ok
return True to indicate success, False to indicate failure

Show TOC