int ok = SerializeItem(APTR handle, struct hwSerializeItemInfo *key,
             struct hwSerializeItemInfo *val, struct hwTagList *tags);

Both, the key and the value of the item to serialize are passed using a struct hwSerializeItemInfo pointer. 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 will be set to the type of the key and value to be serialized. This will be one of the following types:

HWSERIALIZETYPE_DOUBLE:

Key or value is a double number. Data will contain a pointer to a double containing that number.

HWSERIALIZETYPE_STRING:

Key or value is a string. Data will contain a pointer to this string. The string needn't be NULL-terminated because Length will be set to the string length in bytes. Note that strings passed as values may also contain binary data. Keys, however, will always be text. If Length is 0 Data will 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 will be NULL. Note that this item will be sent to you twice: When a new table is to be serialized, Length will be set to 1. After that all items of that table will be serialized and then the initial table item will be sent to you again, but now with Length set to 0. Thus, the Length field can be interpreted as opening (1) or closing (0) the table that is to be serialized.

HWSERIALIZETYPE_FUNCTION:

Value is a function. Note that this can only be used for values. Functions cannot be used as keys. Data will be set to a memory buffer containing the byte code of the function. Length will 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:

This can be a combination of the following flags:

HWSERIALIZEFLAGS_SPARSE:

This will be set for all keys that belong to a sparse table.

HWSERIALIZEFLAGS_BINARY:

This will be set for all keys that belong to a table that has values that use binary data (e.g. functions or strings that have binary data).

HWSERIALIZEFLAGS_NUMIDX:

This will be set for all keys that belong to a table that has keys at numeric indices. Note that tables can have both, numeric and string, indices. (V10.0)

HWSERIALIZEFLAGS_STRIDX:

This will be set for all keys that belong to a table that has keys at string indices. Note that tables can have both, numeric and string, indices. (V10.0)

HWSERIALIZEFLAGS_KEYVAL:

This will be set if the table that is about to be opened or closed consists only of string indices that are named key and value. If it is set, it will be passed to your function in the item that opens or closes the table, i.e. the item whose Type member of the val pointer is set to HWSERIALIZETYPE_TABLE.

Note that to serialize the data, SerializeItem() has to call the writefunc() that was passed to your plugin when Hollywood called your InitSerializer() function. See InitSerializer for details. This function looks like this:

int writefunc(APTR data, int len, APTR userdata);

The following arguments must be passed:

data:

The data to serialize.

len:

The length of the data in bytes.

userdata:

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

The return value of writefunc() will be the number of bytes successfully written. If this is not the same as len (or any other error has occurred), SerializeItem() should return False to indicate an error.

handle

serializer handle allocated by InitSerializer()

key

key of the item to serialize

val

value of the item to serialize

tags

reserved for future use, currently always NULL

ok

return True to indicate success, False to indicate failure